Skip to content
ffinn

How it works

From one sentence to production.

ffinn starts you on a solid, protected core. The build agent adds the features your business needs on top, following your architecture, checking its own work, and stopping for your review before anything goes live.

steps from request to release
9
steps from request to release
AI provider options
7
AI provider options
self-correction attempts
3
self-correction attempts
core files the agent can write
0
core files the agent can write

The foundation

Start on a core the AI can't touch.

Before the agent writes anything, ffinn already ships what every application needs and nobody wants to build twice. Those modules are protected: the agent can read them, but it can never change them.

That is intentional. Authentication, billing and permissions are the riskiest parts of any product. They stay hand-written, reviewed and under your version control.

Your features
Written by the agent from your requests: models, services, APIs and pages
Architecture check
Every generated file is validated before it is committed
↕ validates
ffinn core
Auth · tenancy · roles · billing · notifications · audit
protected
Infrastructure
PostgreSQL · SQLAlchemy · FastAPI · Next.js · Docker

Step by step

Nine steps. You approve the ones that matter.

  1. 01
    Setup

    Connect your AI provider

    Open AI Agent → Providers and add a key for the model you want to use. ffinn tests the connection and lists the available models before you save.

    • Keys are encrypted before they are stored in your database
    • Pay your provider directly, with no markup in between
    • Switch providers or models at any time
  2. 02
    Setup

    Connect your repository

    Link the GitHub repository that holds your copy of ffinn. The agent reads it to learn your existing models, services and screens before it writes a line.

    • The access token is encrypted and stored per tenant
    • Set a branch prefix such as ai-agent/ to keep generated work tidy
    • Point ffinn at your staging and release workflows in GitHub Actions
  3. 03
    Generate

    Describe the feature

    Write what you need in plain language. You do not need to know how the codebase is organised; the agent maps your request onto it.

    • Go as broad as “add a booking system” or as precise as you like
    • Name the fields, relationships and business rules that matter to you
    • The request is mapped to each layer: model, service, API and page
  4. 04
    Generate

    The agent reads, then writes

    Before generating, the agent pulls in the neighbouring code your feature will touch. The result fits your project from the first draft.

    • Model, schema, service, API route and page are generated in one pass
    • Services are injected with FastAPI dependencies; routes stay thin
    • Pages use the shared API client and TypeScript types
    • New features are wired into navigation, permissions and the API router
  5. 05
    Validate

    Architecture check

    Every generated file is validated before it is committed. If something breaks the rules, the agent gets a focused correction prompt explaining each problem and tries again.

    • Every new domain model must be tenant-scoped
    • Routes may not query the database or open sessions directly
    • Services may not depend on web-layer types
    • Protected core files are stripped from the output
  6. 06
    Review

    Review the pull request

    The change is committed to a new branch and opened as a pull request. Read the diff in GitHub with your normal review process, then approve, request changes or close it.

    • One request becomes one branch and one pull request
    • The description summarises what was built and which files changed
    • Security, configuration and infrastructure files are never overwritten
  7. 07
    Stage

    Deploy to staging

    Trigger a staging deploy from the AI Agent dashboard. ffinn runs your GitHub Actions workflow and streams progress back to the page as it happens.

    • Runs the staging workflow you configured in step 2
    • Live status over WebSockets, with no page refresh
    • Database migrations run automatically when the new version starts
  8. 08
    Test

    Try it, refine it

    Use the feature in staging with realistic data. If it needs adjusting, write a follow-up request; the agent reads its earlier work and makes a focused change on top.

    • Run your own end-to-end checks against the staging link
    • Follow-up requests build on the existing generated files
    • Each change is its own small, reviewable pull request
  9. 09
    Ship

    Release to production

    When staging looks right, release from the dashboard. The same pipeline and the same build go to production. If something is off, revert the generation.

    • Production runs the release workflow you configured
    • Deployment status streams back live, as it did for staging
    • Every generation is kept with its request, files, branch, pull request and deploy history

Iteration

Requirements change. So do your requests.

You never regenerate from scratch. Each follow-up reads the code that is already there and applies a small, reviewable change.

Add a field

“Add an optional notes field to Customer and show it on the form”

Model, schema and form updated together

Tighten permissions

“Only admins can delete a customer”

Route permission updated, role mapping seeded

Add an endpoint

“Export customers to CSV, filtered by date range”

New route, service query and streamed CSV response

Connect features

“Email new customers a welcome message”

Notification call added to the customer service

  1. Request
  2. Read existing code
  3. Generate change
  4. Check architecture
  5. Pull request
  6. Merge

Guardrails

The agent can't break your architecture.

Rules are enforced in code, not left to the prompt. A violation triggers a targeted correction, not a broken commit.

  • Protected core files. Security, configuration, infrastructure and shared components are on a deny-list.

  • Layer boundaries. Routes call services; services own the logic. Shortcuts are rejected.

  • Tenant isolation. Every new model is tenant-scoped, so customer data stays separate.

  • Bounded edits. Navigation, permissions and the API router are updated through controlled merge points only.

Architecture checkpassed
  1. ffinn check ai-agent/online-booking
  2. models/booking.py · tenant-scoped · SQLAlchemy 2.0 Mapped[]
  3. services/booking_service.py · no web-layer imports
  4. schemas/booking_schemas.py · Pydantic v2
  5. api/bookings.py · direct database query in route
  6. Sending a targeted fix to the model · attempt 2 of 3
  7. api/bookings.py · logic moved to BookingService
  8. 6 of 6 files pass · 0 protected files touched
  9. Pull request #48 opened for your review

See it build your first feature.

Free and MIT licensed. Bring your own AI key, run it on your own machine, and keep everything it writes.

Get started free Read the docs
$ git clone https://github.com/bplogan/ffinn.git && cd ffinn && docker compose up