Date: July 8, 2025 14:38 ET

Fastable is an open-source, browser-based AI application builder designed to radically simplify the process of creating and deploying full-stack web applications. It bridges the gap between a simple natural language prompt and a production-ready, deployed application built on the robust FastAPI full-stack template.

The core philosophy is to empower developers by combining a conversational AI interface with a professional, Git-based workflow. Users interact with an AI agent to build, test, iterate, and deploy their applications, with GitHub serving as the source of truth and the primary interface for code review. This eliminates local setup friction while preserving control, transparency, and engineering standards.

This document outlines the complete architecture and phased implementation plan to build Fastable from the ground up.

• Browser-First, CLI-Optional: All essential developer actions—editing, testing, committing, deploying—are available via a rich browser interface. Users can clone the Git repo and continue work locally via CLI with no vendor lock-in.

• Git is the Source of Truth: Application code, configuration, and history are stored in Git. All commits, branches, diffs, and pushes are first-class operations. There is no proprietary format.

• Staging & Commit Workflow: Every project runs in a staging container for live testing. Commits occur only after passing validation, preserving a clean Git history.

• Secure, Isolated Agent Execution: All AI-driven actions (code generation, linting, testing, formatting, command execution) occur inside ephemeral Docker containers. These provide full dependency isolation, reproducibility, and strict boundary control.

• Planner-Executor Architecture: The AI agent is split into a planner (which emits structured tool plans) and an executor (which executes tools step-by-step). This supports observability, safety, and testability.

• Declarative Tool Protocol: Tool invocations are represented in JSON format and follow a schema. Each step explicitly invokes a tool with typed parameters.

• Safe Execution Gatekeeping: Destructive actions (e.g., shell commands, file deletes) are guarded by a safety validator. User confirmation is required before execution.

• Persistent Project Memory: Each project includes a .fastable.md file containing goals, TODOs, naming conventions, and design notes. This is injected into prompts and versioned with code.

• Anonymous Usage Telemetry (Required): Tool usage, error rates, and planning durations are logged anonymously for system optimization. Opt-out is planned for future versions.

• No File Tree UI (MVP): The MVP deliberately omits a graphical file tree to reduce scope and complexity. This may be added in a future milestone.

• Authentication: User signs in with GitHub via OAuth and authorizes repo access.
• Project Creation: A new project is scaffolded locally and a private GitHub repo is created.
• Start Session: User launches a new chat session, which boots the app container via Docker Compose.
• Give Prompt: User enters a natural language instruction.
• Planning: Agent emits a structured plan in JSON (tool invocations).
• Execution: Executor runs tools step-by-step, streaming results to the chat.
• Live App Preview: The full-stack app runs in an iframe with live reload or restart.
• Log Monitoring: Logs from frontend, backend, and browser are streamed. Errors are detected and injected into chat.
• Git Diff Viewer: Displays current changes from git diff --cached.

1. LLM generates commit message.
2. Code is auto-linted, type-checked, and tested.
3. If any check fails, the agent attempts auto-repair.
4. On success, commits are made and pushed.
5. GitHub Actions build is triggered. Logs are streamed into chat for failure diagnosis.

Single-host, multi-project architecture using Docker for process isolation.

• Chat UI
• Session Manager
• Log Viewer
• Diff Viewer
• Plan Visualizer
• Commit & Deploy Interface
• CI Status Dashboard

• REST + WebSocket APIs
• GitHub OAuth
• Session orchestration
• Agent and App management
• Log streaming
• Procrastinate for async jobs

• Short-lived per-request container
• Executes tool plan steps
• Mounts project volume
• Destroys itself post-task

• Long-running docker-compose stack (FastAPI, frontend, Postgres)
• Used for live preview and testing
• Isolated from agent

• Routes requests to per-project subdomains
• Projects run in isolated Docker networks

• Postgres-backed queue (Procrastinate)
• Executes background jobs: LLM calls, shell commands, builds

• Each project lives at /home/fastable/projects/<slug>/
• Unique Docker network per project
• Agent/App containers share a network but no filesystem access

[
  { "tool": "ReadFile", "params": { "path": "backend/app/api.py" } },
  { "tool": "EditFile", "params": { "path": "backend/app/api.py", "edits": [{ "line": 12, "new_content": "..." }] } },
  { "tool": "RunShell", "params": { "command": "pytest tests/" } }
]

• ReadFile

• WriteFile

• EditFile

• Glob

• Grep

• RunShell (guarded + confirmed)

  • guarded: execution is blocked by default and only allowed if it passes a predefined safety check (e.g. regex allowlist, static analysis).
  • confirmed: execution requires explicit user approval before running (e.g. via a UI prompt).

• RunTests

• GitStatus

• GitDiff

• GitAddCommitPush

• FetchGitHubActionsLogs

• Every tool invocation is JSON-based.
• Plans must conform to the declared JSON schema.
• tool_protocol_version is tracked per plan.

• Git operations executed inside agent container via CLI
• Staged changes displayed via git diff --cached
• LLM suggests commit messages
• GitHub Actions runs on push
• CI logs retrieved via GitHub API and shown inline
• Future: PR creation, branch management, and co-author metadata

• MVP (Staging): Secrets are encrypted using Fernet and stored in Postgres. Injected at runtime via volume or env.
• MVP (Production): Secrets written to GitHub Secrets using GitHub API.
• Planned: Pulumi-based BYOC (Bring Your Own Cloud) secrets provisioning and runtime access.

• .fastable.md is stored in the project root and versioned in Git.

Used to retain:

• Project goals
• Naming conventions
• Known issues
• Design history

Contents are injected into the LLM context on each session.

class User(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    email: str = Field(index=True)
    github_id: Optional[int] = Field(unique=True)
    github_username: Optional[str] = None
    github_access_token: Optional[str] = None
    is_superuser: bool = False
    is_active: bool = True
    projects: list["Project"] = Relationship(back_populates="owner")

class Project(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    name: str
    local_path: str
    github_repo_url: Optional[str] = None
    owner_id: uuid.UUID = Field(foreign_key="user.id")
    created_at: datetime = Field(default_factory=datetime.utcnow)
    owner: User = Relationship(back_populates="projects")
    sessions: list["ChatSession"] = Relationship(back_populates="project")

class ChatSession(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    project_id: uuid.UUID = Field(foreign_key="project.id")
    name: str
    created_at: datetime = Field(default_factory=datetime.utcnow)
    project: Project = Relationship(back_populates="sessions")
    messages: list["ChatMessage"] = Relationship(back_populates="session")
    tasks: list["Task"] = Relationship(back_populates="session")

class ChatMessage(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    session_id: uuid.UUID = Field(foreign_key="chatsession.id")
    role: str
    content: str
    metadata: dict = Field(default_factory=dict, sa_column=Column(JSON))
    created_at: datetime = Field(default_factory=datetime.utcnow)
    session: ChatSession = Relationship(back_populates="messages")

class Task(SQLModel, table=True):
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    session_id: uuid.UUID = Field(foreign_key="chatsession.id")
    procrastinate_job_id: Optional[int] = Field(index=True)
    status: str
    created_at: datetime = Field(default_factory=datetime.utcnow)
    completed_at: Optional[datetime] = None
    session: ChatSession = Relationship(back_populates="tasks")

• Epic 1.1: Auth & User Model

  • GitHub OAuth, project creation, user management

• Epic 1.2: Workspace Setup

  • FastAPI template scaffold, GitHub repo creation, Git service layer

• Epic 1.3: Staging Env

  • Docker-compose boot, iframe integration, log viewer

• Epic 1.4: Manual Commit Flow

  • Git diff UI, manual commit input, CI integration

• Epic 2.1: Planner + Executor

  • Tool plan JSON schema, agent container loop, safety validation

• Epic 2.2: Context Injection

  • File summaries, diffs, errors, .fastable.md merged into prompt

• Epic 2.3: Tooling

  • Implement tool runner framework and safety wrappers

• Epic 2.4: Feedback Loop

  • Log/error injection, auto-fix, test/lint, CI log parsing

• Plan preview/edit interface
• Sub-agent delegation for large tasks
• Semantic code search via embeddings
• .fastable.md editor UI
• Production deployment endpoint (e.g., *.fastable.dev)
• Plugin system for custom tools and agent models
• Long-term memory and conversation recall
• Test case generation
• Opt-out telemetry switch
• File tree and inline code editor
• Multi-tenant Kubernetes deployment model

• WindSurf: Live planning threads, rich persistent memory, test-triggered cascades
• Claude Code: REPL interface, tool invocation DSL, .md-based memory
• lovable.dev: Plan visualizer, YAML-based declarative tooling, modular shell actions

Fastable combines the best of all three—declarative tool planning, conversational agent interface, and robust Git-based workflows—within a secure, browser-first application builder.