# rajaram-mohanty/genforge architecture

> Architecture diagram of the GitHub repository rajaram-mohanty/genforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajaram-mohanty/genforge
- Repository: https://github.com/rajaram-mohanty/genforge

## Overview

##### Project Type and Purpose
- GenForge is a full-stack web application platform that lets users generate complete web apps via natural-language prompts.
- Frontend: EJS views, CSS/JS assets (Monaco Editor integration, live preview panels).
- Backend: Express.js server, session-based authentication, virtual file system, AI code generation engine.
- External Service: Google Gemini AI for code generation.

##### File Structure
- Top-level files:
- server.js / index.js / agent.js: Express app and AI agent logic
- virtual-file-system.js: In-memory project VFS
- test-no-duplicate-folders.js: Unit test for VFS
- Directories:
- public/: static assets (CSS, JS, Monaco editor)
- views/: EJS templates (auth, dashboard, preview, error pages)
- Config files: .env (via dotenv), package.json, .gitignore
- Patterns: MVC-like separation (views/ for presentation, server.js routing/controllers, VFS as model), API routes under /api/*.

##### Key Insights from README
- Architecture Overview: Frontend ↔ Backend ↔ AI Service triangle.
- Core Components: Authentication, AI Code Generation Engine, Virtual File System, Real-Time Code Editor, Application Preview.
- Tech stack: Node.js, Express, EJS, Monaco Editor, Google Gemini AI client.

##### Main Components
a. Frontend Layer
- EJS Views & Static Assets (HTML/CSS/JS).
- Monaco Editor client component for code editing.
- Live Preview iframe or renderer.
b. Backend Layer
- Express Server (server.js / index.js) handling HTTP & template rendering.
- Authentication Module (bcryptjs, express-session).
- API Layer (/api/generate-prompt, /api/update-file, etc.).
- Virtual File System module (virtual-file-system.js).
- AI Agent (agent.js) invoking Google Gemini via Generative AI SDK.
c. External Services
- Google Gemini AI (code generation service).
d. Data Stores / State
- In-memory VFS (project structure & file contents).
- Session store (express-session, default in-memory or configurable store).
e. (Future) Database Layer
- Placeholder for persistent storage if database integration is added.

##### Relationships & Data Flows
- User Browser ↔ HTTP(S) ↔ Express Server
- Express Server renders EJS views and serves static assets.
- Frontend scripts call backend API endpoints (AJAX/fetch) for code generation, file CRUD, preview.
- Backend API → Virtual File System → returns file structure or content.
- Backend API → AI Agent → Google Gemini AI → returns generated code.
- Backend merges AI output into VFS, sends updates to frontend.
- Frontend updates Monaco Editor and Preview pane.

##### Architectural Patterns & Principles
- MVC-style layering: Views (EJS) / Controllers (Express routes) / Model (VFS).
- Modular separation: Authentication, AI Engine, VFS, Editor, Preview.
- Stateless API design, session-based auth.
- Lazy loading of Monaco, debounced updates for performance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Client Side"
        direction TB
        Browser["User Browser"]:::frontend
        subgraph "Frontend Layer"
            direction TB
            Views["EJS Views & Templates"]:::frontend
            AuthPage["Authentication Page Template"]:::frontend
            DashboardPage["Dashboard Page Template"]:::frontend
            PreviewTemplate["Live Preview Panel Template"]:::frontend
            LeftPanel["Left Chat/Input Panel"]:::frontend
            RightPanel["Right Code/Preview Panel"]:::frontend
            ErrorPages["Error & 404 Pages"]:::frontend
            CSSAssets["Static CSS Assets"]:::frontend
            JSAssets["Static JS Assets"]:::frontend
            MonacoEditor["Monaco Editor Integration"]:::frontend
        end
    end

    subgraph "Server Side"
        direction TB
        Express["Express Server"]:::backend
        Auth["Authentication Module"]:::backend
        API["API Layer (/api endpoints)"]:::backend
        VFS["Virtual File System"]:::backend
        Agent["AI Agent Module"]:::backend
    end

    subgraph "External Services"
        direction TB
        Gemini["Google Gemini AI"]:::external
    end

    %% Connections
    Browser -->|HTTP Request| Express
    Express -->|renders| Views
    Express -->|renders| AuthPage
    Express -->|renders| DashboardPage
    Express -->|renders| PreviewTemplate
    Express -->|renders| LeftPanel
    Express -->|renders| RightPanel
    Express -->|renders| ErrorPages
    Express -->|serves| CSSAssets
    Express -->|serves| JSAssets
    Express -->|serves| MonacoEditor
    Browser -->|AJAX/fetch| API
    API -->|read/write| VFS
    API -->|invoke| Agent
    Agent -->|calls| Gemini
    Gemini -->|responds| Agent
    Agent -->|writes| VFS
    VFS -->|provides| API
    API -->|responds| Browser

    %% Click Events
    click Views "https://github.com/rajaram-mohanty/genforge/tree/main/views/"
    click AuthPage "https://github.com/rajaram-mohanty/genforge/blob/main/views/auth.ejs"
    click DashboardPage "https://github.com/rajaram-mohanty/genforge/blob/main/views/dashboard.ejs"
    click PreviewTemplate "https://github.com/rajaram-mohanty/genforge/blob/main/views/preview.ejs"
    click LeftPanel "https://github.com/rajaram-mohanty/genforge/blob/main/views/left-panel.ejs"
    click RightPanel "https://github.com/rajaram-mohanty/genforge/blob/main/views/right-panel.ejs"
    click ErrorPages "https://github.com/rajaram-mohanty/genforge/blob/main/views/error.ejs"
    click ErrorPages "https://github.com/rajaram-mohanty/genforge/blob/main/views/404.ejs"
    click CSSAssets "https://github.com/rajaram-mohanty/genforge/tree/main/public/css/"
    click JSAssets "https://github.com/rajaram-mohanty/genforge/tree/main/public/js/"
    click MonacoEditor "https://github.com/rajaram-mohanty/genforge/blob/main/public/js/monaco-editor.js"
    click Express "https://github.com/rajaram-mohanty/genforge/blob/main/server.js"
    click Express "https://github.com/rajaram-mohanty/genforge/blob/main/index.js"
    click Auth "https://github.com/rajaram-mohanty/genforge/blob/main/server.js"
    click API "https://github.com/rajaram-mohanty/genforge/blob/main/server.js"
    click API "https://github.com/rajaram-mohanty/genforge/blob/main/index.js"
    click VFS "https://github.com/rajaram-mohanty/genforge/blob/main/virtual-file-system.js"
    click Agent "https://github.com/rajaram-mohanty/genforge/blob/main/agent.js"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
