AI Agent - End to End

How the AI Agent
Extends Your App

ffinn ships a production-hardened core. The AI agent adds your custom features on top - following every pattern, enforcing every rule, generating every layer - from database to UI.

The Foundation

Start with a hardened
production core

Before the AI agent writes a single line, ffinn already ships with everything that every application needs - and that nobody wants to write twice. These modules are protected files the AI agent can never modify.

That protection is intentional. Authentication, billing, and permissions are the most critical parts of any application. They stay hand-written, reviewed, and version-controlled by you.

Auth & 2FA
JWT + Refresh Tokens
Multi-Tenancy
Stripe Billing
Feature Paywall
Role-Based Access
Audit Logging
Background Jobs

Layered Architecture

Your Custom Features
Generated by the AI agent - entities, services, APIs, UI
↕ Pattern Enforcement Layer
Validates every generated file before it is committed
ffinn Core Framework
Auth · Billing · RBAC · Multi-Tenancy · Jobs · Audit - PROTECTED
Infrastructure
PostgreSQL · SQLAlchemy · FastAPI · Next.js · Stripe
Step by Step

From prompt to production
in nine steps

Each step is designed to keep you in control while the AI handles the heavy lifting.

01Setup

Add Your AI Provider

Navigate to AI Agent → Settings and add your API credentials. ffinn supports OpenAI, Anthropic, Google Gemini, Azure OpenAI, and Ollama for fully local generation.

Your API key is encrypted with AES-256 before storage - it never leaves your infrastructure in plaintext
A quick connectivity test fires when you save to confirm the key is valid
Switch providers or models at any time - no lock-in

Supported Providers

  • OpenAI - gpt-4o, gpt-4-turbo
  • Anthropic - claude-3.5-sonnet
  • Google - gemini-1.5-pro
  • Azure OpenAI - any deployment
  • Ollama - local, zero cost
02Setup

Connect Your Repository

Link your GitHub, GitLab, or Azure DevOps repository. The AI agent reads your codebase to understand existing patterns before it writes a single line.

Your repository access token is encrypted and stored per-tenant
The agent reads relevant source files as context before generating - it knows your existing naming conventions, existing entities, and project structure
Configure a branch prefix (e.g. ai-agent/) so generated branches stay organized

Configured Per Generation

  • Target branch prefix
  • Default commit message template
  • PR title & description defaults
  • Staging & release workflow IDs
03Generate

Write Your Prompt

Describe the feature you want in plain language. The more context you provide, the better the output. You don't need to know the codebase structure - the agent figures that out.

Prompts can be as high-level as "Add a booking system with date ranges and availability" or as specific as you like
Mention field names, relationships, or business rules you care about
The agent automatically maps your intent to ffinn's layered architecture - domain model, service, API endpoint, React component

Example Prompts

  • "Create a Customer entity with name, email, and phone"
  • "Build a product catalog with categories and search"
  • "Add a dashboard widget for monthly revenue"
  • "Generate an invoice system with PDF export"
04Generate

AI Reads, Then Writes

Before generating anything, the agent fetches existing files from the bounded context - currently-existing models, services, and endpoints that neighbouring code touches. Output is architecturally consistent from the start.

Domain models, services, API routers, and frontend components are all generated in one pass
Generated code follows ffinn's exact patterns: every model includes tenant_id, created_at, updated_at, and is_deleted
Services are injected via FastAPI Depends; API routers never contain business logic
Frontend components use the established axios API client and TypeScript interfaces

Files Typically Generated

  • app/domain/models/my_entity.py
  • app/services/my_entity_service.py
  • app/api/my_entity.py (router)
  • app/schemas/my_entity_schemas.py
  • src/app/app/my-entity/ (Next.js page)
05Validate

Pattern Enforcement

Every generated file is run through a validator before it is committed. If the code violates architecture rules, the agent self-corrects - up to 3 times - with a focused prompt explaining each violation.

Domain models must include tenant_id, created_at, and is_deleted
Services must not import from the API layer (no upward dependency)
API routers must delegate all logic to services - no direct DB queries
New files must land in the correct module directory and not overlap CORE files

Self-Correction Loop

  • 1st pass - generate full output
  • Validate against architecture rules
  • Violation found → retry with targeted correction prompt
  • Up to 3 retries before graceful failure with explanation
06Review

Review the Output

Generated files are committed to a new branch in your repository. Open the pull request to see a clean diff - exactly what changed versus main. Approve, request changes, or close it - you stay in control.

Each generation creates one branch and one pull request
The PR description summarises what was built and which files were changed
Review in GitHub / GitLab / Azure DevOps with your normal code-review workflow
Any file in the CORE framework is protected - the agent can never overwrite auth, billing, or permission files

Branch Naming

  • Default prefix: ai-agent/
  • Example: ai-agent/add-booking-system
  • Configurable per-tenant
  • One branch = one logical feature
07Stage

Deploy to Staging

When you're happy with the review, trigger a staging deployment directly from the AI Agent dashboard. The agent merges the branch, runs your CI workflow, and reports the deployment URL back in real time via WebSocket.

Integrates with GitHub Actions, GitLab CI, and Azure Pipelines
Configure staging and release workflow IDs per-tenant in AI Agent → Settings
WebSocket stream shows build log and deployment status live - no page refresh needed
The staging environment is a full copy of production infrastructure - same migrations, same seed data shape

Staging Checklist

  • Branch merged to staging branch
  • CI workflow triggered automatically
  • Database migrations applied
  • Deployment URL returned to dashboard
  • Verification stage (optional) blocks prod
08Test

Test in Staging

Exercise your new feature against real data in staging. If something needs fine-tuning, write a follow-up prompt - the AI agent generates an incremental patch on top of the existing generation.

Run your end-to-end tests against the staging URL
For changes: write a follow-up prompt referencing the original feature - the agent reads the existing generated files as context
Each edit generates a new branch and PR, keeping each change atomic and reviewable
Mark staging as verified in the dashboard to unlock the production deployment button

Iterating on Generations

  • "Add a nullable notes field to the booking"
  • "Restrict booking creation to admin role only"
  • "Add pagination to the booking list endpoint"
  • Each change is a separate, reviewable PR
09Ship

Deploy to Production

One click in the dashboard triggers your production workflow. The same CI/CD pipeline - same migrations, same artifact. Your new feature is live.

Production deployment requires staging verification to be marked complete (configurable)
Alembic migrations run automatically as part of the deployment startup
Deployment status streams back in real time via the same WebSocket channel
The generation is archived with full metadata: prompt, files changed, branch, deployment timestamps

Deployment Audit Trail

  • Original prompt stored permanently
  • AI provider & model version logged
  • Files changed with diffs archived
  • Branch, PR, and deployment links preserved
Iteration

Features evolve.
So do your prompts.

You don't re-generate from scratch when requirements change. Each follow-up prompt reads the existing generated code as context and applies a surgical, reviewable patch.

Add a field

Prompt

"Add a nullable notes field to the Customer entity and surface it in the form"

Alembic migration + model update + schema update + form field added

Tighten permissions

Prompt

"Restrict Customer delete to admin role only, and log the action to the audit trail"

Router permission decorator updated + audit log call added in service

Add an endpoint

Prompt

"Add an export-to-CSV endpoint for Customers filtered by date range"

New router endpoint + query filter + streaming CSV response

Cross-feature wiring

Prompt

"When a new Customer is created, send them a welcome email using the email template system"

Email service call injected into Customer service create method

Prompt
Read Context
Generate Patch
Validate
PR → Merge
Pattern Validator Output
> Validating generated files…
> app/domain/models/booking.py - tenant_id present
> app/domain/models/booking.py - is_deleted present
> app/services/booking_service.py - no API layer imports
> app/api/booking.py - direct DB query found
> Violation: API router must delegate to service layer
> Retrying with architecture-violation correction…
> app/api/booking.py - all queries delegated to service
> All 5 files passed validation
> Committing to branch ai-agent/add-booking-system…
> PR #47 opened
Architecture Guard

The AI can't break your architecture

Every file the agent writes is validated against a strict set of architectural rules before it is committed. Violations trigger a targeted self-correction loop, not a fatal error.

Protected core files
Auth, billing, permissions, and middleware are on a deny list - the agent can never write to them
Layer boundary enforcement
API routers → Services → Models. Upward imports are detected and rejected
Required fields on every model
tenant_id, created_at, updated_at, and is_deleted must appear on every new domain model
Self-correcting retry loop
Up to 3 attempts with a targeted correction prompt before the generation fails gracefully
9
Steps to Production
5
AI Providers
3
Self-Correction Retries
100%
Core Files Protected

Ready to see it
in action?

We're putting the finishing touches on the launch. Sign up for early access and be the first to build with ffinn.

Bring your own API keys. No markup. No vendor lock-in.