# jatingarg619/saas-builder architecture

> Architecture diagram of the GitHub repository jatingarg619/saas-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jatingarg619/saas-builder
- Repository: https://github.com/jatingarg619/saas-builder

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based CLI tool (saas-builder) whose sole purpose is to scaffold production-ready full-stack Next.js/Supabase SaaS apps automatically using AI models.
- Key capabilities: interactive CLI commands, AI-powered code generation, template management, build orchestration, and external API integration (OpenAI, Anthropic, Gemini, Supabase).

##### File Structure
- Top-level:
- `.env.sample`, `.gitignore`, `LICENSE`, `README.md`
- `pyproject.toml`, `requirements.txt`
- The `gocodeo_cli/` package contains:
– `cli.py` (entry point)
– `commands/` (Command pattern modules: `init`, `build`)
– `agents/` (orchestrators: `base.py`, `build_agent.py`)
– `services/` (abstractions over LLM, project state)
– `tools/` (shell wrappers: npm, SQL migrations, env management, build tools)
– `templates/` (prompt templates & ZIP’ed app-template stacks)
– `utils/config.py` (configuration loader)

##### Extract Additional Insights from README
- The architecture is pipeline-driven:
CLI → select template & tech stack → configure Supabase → call AI model → scaffold code → run build steps (npm install, db migrations) → start dev server.
- Dependencies: Next.js, Supabase, TypeScript, real-time features.

##### Main Components & Interactions
a. Components
1. **CLI Entry Point** (`saas-builder`, `cli.py`)
2. **Command Modules** (`commands/init.py`, `commands/build.py`)
3. **Agents** (`agents/base.py`, `agents/build_agent.py`)
4. **Services**
– **LLMService** (`services/llm_service.py`): wraps OpenAI/Anthropic/Gemini calls
– **ProjectState** (`services/project_state.py`): tracks user inputs, template choices, generated files
5. **Tools**
– **EnvTools** (load/write `.env`)
– **NpmTools** (npm install, npm run dev)
– **SqlTools** (run migrations via Supabase CLI or psql)
– **BuildTools** (file scaffolding, zip extraction)
6. **Templates** (`templates/prompts/*.txt`, `templates/stacks/*.zip`)
7. **External Services**
– AI Providers (OpenAI, Anthropic, Google)
– Supabase (Auth, PostgreSQL, real-time)
8. **File System** (writes the generated Next.js project)

b. Relationships / Data Flows
- User invokes `saas-builder init` → CLI loads configuration → Command module delegates to BuildAgent
- BuildAgent sequences: prompt user → fetch/generate code via LLMService → write code using BuildTools → install deps via NpmTools → configure database via SqlTools → spin up dev server
- ProjectState maintains context and intermediate results passed between modules
- EnvTools reads/writes API keys for Supabase & AI models
- Templates feed static files & prompt blueprints into agents

##### Architectural Patterns & Design Principles
- **Command Pattern**: Each CLI command is a pluggable module under `commands/`.
- **Orchestrator/Agent**: Business logic centralized in `build_agent.py`, decoupled from CLI wiring.
- **Service Abstraction**: External API calls (LLM, Supabase) behind service interfaces.
- **Tool Wrappers**: Shell commands abstracted in `tools/` to allow mocking, testing.
- **Template-Driven Generation**: Prompts and project starters in `templates/`.

##### Essential Details to Capture
- The **entry flow** (`cli.py` → command → agent)
- The **AI invocation** path (through `llm_service.py` to external LLMs)
- The **Scaffolding & Build** path (templates → build_tools → npm_tools → proj filesystem)
- The **Database Setup** path (sql_tools → Supabase)
- **Config management** (`utils/config.py`, `.env` handling)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entry Point\n(cli.py)"]:::blue
    end

    %% Command Modules
    subgraph "Command Modules"
        Init["Init Command\n(init.py)"]:::blue
        Build["Build Command\n(build.py)"]:::blue
    end

    %% Agents
    subgraph "Agents"
        BaseAgent["Base Agent\n(base.py)"]:::blue
        BuildAgent["Build Agent\n(build_agent.py)"]:::blue
    end

    %% Services
    subgraph "Services"
        LLMService["LLM Service\n(llm_service.py)"]:::green
        ProjectState["Project State\n(project_state.py)"]:::green
    end

    %% Tools
    subgraph "Tools"
        EnvTools["EnvTools\n(env_tools.py)"]:::orange
        NpmTools["NpmTools\n(npm_tools.py)"]:::orange
        SqlTools["SqlTools\n(sql_tools.py)"]:::orange
        BuildTools["BuildTools\n(build_tools.py)"]:::orange
    end

    %% Templates
    subgraph "Templates"
        PromptTemplates["Prompt Templates\n(prompts/*.txt)"]:::yellow
        StackTemplates["Starter Project Stacks\n(stacks/*.zip)"]:::yellow
    end

    %% External Systems
    subgraph "External Systems"
        OpenAI["OpenAI / Anthropic / Gemini"]:::gray
        SupabaseService["Supabase Auth & Postgres"]:::gray
    end

    %% File System
    subgraph "File System"
        ProjectFS["Generated Project Files"]:::purple
    end

    %% Config & Metadata
    subgraph "Config & Metadata"
        EnvSample[".env.sample"]:::purple
        ConfigLoader["Config Loader\n(utils/config.py)"]:::purple
        PyMeta["pyproject.toml, requirements.txt,\nREADME.md, LICENSE, .gitignore"]:::purple
    end

    %% Connections
    CLI -->|"init command"| Init
    CLI -->|"build command"| Build

    Init -->|"delegate to"| BaseAgent
    Build -->|"delegate to"| BuildAgent

    BaseAgent -->|"uses"| ProjectState
    BuildAgent -->|"uses"| ProjectState

    BaseAgent -->|"call LLM API"| LLMService
    BuildAgent -->|"call LLM API"| LLMService

    BuildAgent -->|"scaffold code"| BuildTools
    BuildAgent -->|"install deps"| NpmTools
    BuildAgent -->|"run migrations"| SqlTools
    BuildAgent -->|"write files"| ProjectFS

    EnvTools -->|"manage .env"| ProjectFS
    ConfigLoader -->|"load config"| EnvTools

    LLMService -->|"API calls"| OpenAI
    SqlTools -->|"DB setup"| SupabaseService

    PromptTemplates -->|"provide prompts"| BaseAgent
    PromptTemplates -->|"provide prompts"| BuildAgent
    StackTemplates -->|"provide template stacks"| BuildTools

    %% Click Events
    click CLI "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/cli.py"
    click Build "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/commands/build.py"
    click Init "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/commands/init.py"
    click BaseAgent "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/agents/base.py"
    click BuildAgent "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/agents/build_agent.py"
    click LLMService "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/services/llm_service.py"
    click ProjectState "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/services/project_state.py"
    click EnvTools "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/tools/env_tools.py"
    click NpmTools "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/tools/npm_tools.py"
    click SqlTools "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/tools/sql_tools.py"
    click BuildTools "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/tools/build_tools.py"
    click PromptTemplates "https://github.com/jatingarg619/saas-builder/tree/main/gocodeo_cli/templates/prompts/"
    click StackTemplates "https://github.com/jatingarg619/saas-builder/tree/main/gocodeo_cli/templates/stacks/"
    click ConfigLoader "https://github.com/jatingarg619/saas-builder/blob/main/gocodeo_cli/utils/config.py"
    click EnvSample "https://github.com/jatingarg619/saas-builder/blob/main/.env.sample"
    click PyMeta "https://github.com/jatingarg619/saas-builder/blob/main/pyproject.toml"

    %% Styles
    classDef blue fill:#cfe2f3,stroke:#084c61;
    classDef green fill:#d9ead3,stroke:#274e13;
    classDef orange fill:#ffe599,stroke:#b57f00;
    classDef yellow fill:#fff2cc,stroke:#7f6000;
    classDef gray fill:#dddddd,stroke:#666666;
    classDef purple fill:#ead1dc,stroke:#860d4f;
```
