# suhailult777/ai-coder-main architecture

> Architecture diagram of the GitHub repository suhailult777/ai-coder-main, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suhailult777/ai-coder-main
- Repository: https://github.com/suhailult777/ai-coder-main

## Overview

##### Project type and purpose
- This is a full-stack web application: a browser-based AI-powered code editor with secure authentication and an autonomous “agent mode.”
- Purpose: let authenticated users generate code via AI models, toggle into agent mode for autonomous tasks (file creation, VSCode integration, command execution), and view real-time streaming results.

##### File structure
- Top-level directories:
- frontend/ – static UI: index.html, script.js, styles.css
- backend/
– server/ – Express.js server setup, auth, database drivers, storage abstraction
– api/ – REST endpoints (auth, agent, health, database, SSE stream)
– agent/ – agent logic, status JSON
– scripts/ – DB migration (JSON→Postgres)
- config/ – environment and Firebase config
- test/ – unit, integration, SSE and agent debug tools
- package.json, .env.example – Node.js setup

##### README for additional insights
- Tech stack: HTML/CSS/JS front end, Express/Node.js back end, PostgreSQL or JSON file storage, Firebase for Google Auth, OpenRouter and Gemini 2.0 for AI, SSE for real-time streaming, child process spawning for agent mode.
- Highlights: session-based auth, SSE streams for AI responses, agent’s START→THINK→ACTION→OBSERVE→OUTPUT workflow.

##### Main components and their interactions
a. Frontend UI
– Code editor, model dropdown, auth forms, agent mode toggle, SSE event listener
– Communicates with backend over HTTP(S) and SSE
b. Backend API layer (Express.js)
– /api/auth → login, registration, session management
– /api/agent → spawn agent process (child_process), open VSCode
– /api/agent-stream SSE → stream AI/agent progress to UI
– /api/database → optional DB calls
– /api/health → system and DB status
c. Storage layer
– JSON files (fallback) or PostgreSQL (production)
– Session store: connect-pg-simple or JSON
d. AI services (external)
– OpenRouter API (multiple models)
– Google Gemini 2.0 (primary for agent mode)
e. Firebase Authentication (external)
– Google sign-in integration
f. Agent runtime
– Node.js child processes running agent scripts
– VSCode CLI integration (“code” command)
– Filesystem operations for project scaffolding
g. User’s browser
– Hosts frontend assets, SSE connection, HTTP requests

##### Architectural patterns and design principles
- Layered architecture: Presentation (frontend), API/controllers, business logic (agent, AI integration), data access/storage.
- Separation of concerns: distinct modules for auth, agent, health, database, streaming.
- Event-driven streaming via SSE for real-time feedback.
- Pluggable storage: JSON vs Postgres with migration scripts.
- Externalized configuration for API keys and services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::frontend
    end

    %% Frontend Files
    subgraph "Frontend UI" 
        direction TB
        IndexHTML["index.html"]:::frontend
        ScriptJS["script.js"]:::frontend
        StylesCSS["styles.css"]:::frontend
    end

    Browser -->|"loads"| IndexHTML
    Browser -->|"loads"| ScriptJS
    Browser -->|"loads"| StylesCSS
    Browser -->|"HTTPS Requests"| AuthAPI
    Browser -->|"HTTPS Requests"| CodeGenAPI
    Browser -->|"HTTPS Requests"| AgentAPI
    Browser -->|"SSE Stream"| AgentStreamAPI

    %% Backend Layer
    subgraph "Backend API Server" 
        direction TB
        Server["Express API Server\n(port 3000)"]:::backend
        RoutingIndex["API Index\nbackend/api/index.js"]:::backend
    end

    Server --> RoutingIndex

    %% API Endpoints
    subgraph "API Endpoints"
        direction TB
        AuthAPI["/api/auth"]:::api
        CodeGenAPI["/api/agent"]:::api
        AgentStreamAPI["/api/agent-stream"]:::stream
        DBAPI["/api/database"]:::api
        HealthAPI["/api/health"]:::api
    end

    RoutingIndex --> AuthAPI
    RoutingIndex --> CodeGenAPI
    RoutingIndex --> AgentStreamAPI
    RoutingIndex --> DBAPI
    RoutingIndex --> HealthAPI

    %% Authentication Module
    AuthAPI --> AuthLogic["Auth Logic\nbackend/server/auth.js"]:::backend
    AuthLogic --> FirebaseAuth["Firebase Integration\nbackend/server/firebase-auth.js"]:::backend
    AuthLogic --> ConfigFirebase["Firebase Config\nconfig/firebase-config.js"]:::config
    AuthLogic --> EnvExample[".env.example\nconfig/.env.example"]:::config

    %% Agent Module
    CodeGenAPI --> AgentCore["Agent Core Logic\nbackend/agent/index.js"]:::backend
    AgentCore --> AgentStatus["Agent Status Data\nbackend/agent/agent-status.json"]:::backend
    AgentCore -->|spawn| VSCodeCLI["VSCode CLI"]:::external
    AgentCore -->|filesystem| FSOps["Filesystem Operations"]:::backend

    AgentStreamAPI --> AgentCore

    %% Database Module
    DBAPI --> DBDriver["DB Driver\nbackend/server/database.js"]:::backend
    DBDriver --> StorageJSON["JSON Storage Adapter\nbackend/server/storage.js"]:::backend
    DBDriver --> StoragePG["Postgres Adapter\nbackend/server/storage-postgres.js"]:::backend
    DBDriver --> BackupData["Backup Data JSON\nbackend/server/users.backup.1749496480895.json"]:::backend
    DBDriver --> FallbackData["Fallback JSON\nbackend/server/users.json"]:::backend
    DBDriver --> Migration["Migration Script\nbackend/scripts/migrate-to-postgres.js"]:::backend

    %% Health Check
    HealthAPI --> HealthLogic["Health Logic\nbackend/api/health.js"]:::backend

    %% External Services
    subgraph "External Services"
        direction TB
        FirebaseCloud["Firebase Auth"]:::cloud
        OpenRouter["OpenRouter AI"]:::cloud
        Gemini["Google Gemini 2.0"]:::cloud
    end

    AuthLogic --> FirebaseCloud
    AgentCore --> OpenRouter
    AgentCore --> Gemini

    %% Agent Mode Workflow Annotation
    subgraph "Agent Mode Workflow"
        direction TB
        Start["START"]:::note --> Think["THINK"]:::note --> Action["ACTION"]:::note --> Observe["OBSERVE"]:::note --> Output["OUTPUT"]:::note
    end
    CodeGenAPI --> Start

    %% Streams and Protocols
    AgentStreamAPI -.->|SSE| Browser

    %% Click Events
    click IndexHTML "https://github.com/suhailult777/ai-coder-main/blob/main/frontend/index.html"
    click ScriptJS "https://github.com/suhailult777/ai-coder-main/blob/main/frontend/script.js"
    click StylesCSS "https://github.com/suhailult777/ai-coder-main/blob/main/frontend/styles.css"
    click Server "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/index.js"
    click AuthAPI "https://github.com/suhailult777/ai-coder-main/blob/main/backend/api/auth.js"
    click AuthLogic "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/auth.js"
    click FirebaseAuth "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/firebase-auth.js"
    click ConfigFirebase "https://github.com/suhailult777/ai-coder-main/blob/main/config/firebase-config.js"
    click EnvExample "https://github.com/suhailult777/ai-coder-main/blob/main/config/.env.example"
    click AgentCore "https://github.com/suhailult777/ai-coder-main/blob/main/backend/agent/index.js"
    click AgentStatus "https://github.com/suhailult777/ai-coder-main/blob/main/backend/agent/agent-status.json"
    click CodeGenAPI "https://github.com/suhailult777/ai-coder-main/blob/main/backend/api/agent.js"
    click AgentStreamAPI "https://github.com/suhailult777/ai-coder-main/blob/main/backend/api/agent-stream.js"
    click HealthAPI "https://github.com/suhailult777/ai-coder-main/blob/main/backend/api/health.js"
    click DBAPI "https://github.com/suhailult777/ai-coder-main/blob/main/backend/api/database.js"
    click DBDriver "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/database.js"
    click StorageJSON "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/storage.js"
    click StoragePG "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/storage-postgres.js"
    click Migration "https://github.com/suhailult777/ai-coder-main/blob/main/backend/scripts/migrate-to-postgres.js"
    click BackupData "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/users.backup.1749496480895.json"
    click FallbackData "https://github.com/suhailult777/ai-coder-main/blob/main/backend/server/users.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef api fill:#fff3cd,stroke:#856404,color:#856404;
    classDef stream fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cloud fill:#e2f0fb,stroke:#31708f,color:#31708f;
    classDef note fill:#f8d7da,stroke:#721c24,color:#721c24;
```
