# iamliulv/compoder architecture

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

- Interactive diagram: https://gitdiagram.com/iamliulv/compoder
- Repository: https://github.com/iamliulv/compoder

## Overview

##### Main Layers and Components
- Client / Presentation Layer:
– The “app” directory (with subdirectories like “login”, “main”, “layout”, etc.) reveals that the frontend is built using Next.js. This layer includes UI pages, business components (such as AppHeader, AppSidebarLayout, CodeIDE, CodeRenderer, LoginForm, etc.), and integrated providers (like the LLMSelectorProvider and ProviderModelModal) that manage state and user interactions.
- API / Backend Layer:
◦ “ai-core”: This contains the core logic for AI interactions (with steps like design-component, generate-component, store-component, and a workflow module). These endpoints orchestrate the process of receiving user input, generating component code via AI services, and handling transformation tasks.
◦ “codegen”: Endpoints for listing and retrieving code generation details.
◦ “componentCode”: CRUD endpoints to create, delete, detail, edit, list component codes.
◦ “auth”: Routes for managing authentication (with NextAuth integration).
◦ “config”: Endpoints for handling dynamic configuration changes.
- Services and Business Logic:
– The “app/services” directory (and similar logic in “lib”) abstracts common functionalities and business logic. For instance, the “codegen.service” and “componentCode.service” modules encapsulate the interactions between the API endpoints and underlying logic (such as validation, error handling, and integration with external AI models).
– “lib” further contains configuration, middleware (for auth), and database interaction modules (for MongoDB via Mongoose-like patterns), which show that the project follows a modular design.
- Database / Persistence Layer:
– Within “lib/db”, separate directories exist for “codegen” and “componentCode” that hold schema definitions, migrations, and queries. This indicates MongoDB is used as the primary persistence layer.
- External Services and AI Providers:
– The “app/api/ai-core/utils/aiClient.ts” hints at integration with external AI service providers (e.g., Vercel AI SDK, OpenAI, Claude, etc.), which are essential for generating the component code based on text or image prompts.
- Artifacts and Rendering Sandboxes:
– The “artifacts” directory contains multiple renderer implementations (Antd, Shadcn UI, Mui, Element-Plus, HTML) that serve as sandbox environments to preview or render the generated code. Each is Dockerized and has its own configuration (Dockerfile, next.config, package.json). This separation underscores the project’s flexibility in rendering components with different UI frameworks.

##### Key Relationships and Data Flow
- The user (via the browser) interacts with the Next.js frontend (the “app” layer). From the UI, the user may perform actions such as logging in, specifying code-generating prompts, or editing component code.
- The frontend calls various API endpoints:
– For authentication, it interacts with the “auth” routes.
– For invoking the AI-powered component code generation, it communicates with the “ai-core” endpoints. These endpoints run through defined “steps” (like design, generate, store) to transform the prompt into code.
– For managing component versions and details, the UI reaches endpoints under “componentCode” and “codegen”.
- The API layer dispatches calls to internal service modules (in “app/services” and “lib/”) which process business logic, interact with the database (MongoDB), and send requests to external AI providers.
- Renderers in the “artifacts” folders can be launched independently (often via Docker) to sandbox the generated code visually.

##### Architectural Patterns & Design Principles
- Modularization: Separation into distinct directories for API endpoints, services, and database interactions makes the architecture modular and maintainable.
- Layered Architecture: The separation between presentation (Next.js pages/components), application logic (API endpoints and services), and persistence (MongoDB) is clear.
- Micro-frontends / Independent Artifacts: The existence of independent renderer projects in “artifacts” shows a design pattern where rendering and previewing are decoupled from the main code generation engine.
- Customizability: The project is designed to allow easy customization of code generation based on component libraries, scenarios, etc.
- Integration with External Services: By isolating AI model integrations in dedicated modules (like aiClient.ts and workflow.ts), the design facilitates the use or replacement of different AI models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U("User Browser"):::user

    %% Presentation Layer
    subgraph "Client / Presentation Layer"
        A("Next.js Frontend"):::frontend
        B("UI Components"):::frontend
    end

    %% API / Backend Layer
    subgraph "API / Backend Layer"
        C("API: AI Core"):::backend
        D("API: Auth"):::backend
        E("API: Codegen"):::backend
        F("API: ComponentCode"):::backend
        G("API: Config"):::backend
    end

    %% Services and Business Logic
    subgraph "Services / Business Logic"
        H("Codegen Service"):::services
        I("ComponentCode Service"):::services
        J("Shared Utils & Middleware"):::services
    end

    %% Database / Persistence Layer
    subgraph "Database / Persistence Layer"
        K("MongoDB"):::database
    end

    %% External Services and AI Providers
    subgraph "External Services"
        L("External AI Providers"):::external
    end

    %% Artifacts and Rendering Sandboxes
    subgraph "Artifacts / Renderer Sandboxes"
        M("Antd Renderer"):::renderer
        N("Element Plus Renderer"):::renderer
        O("HTML Renderer"):::renderer
        P("Material UI Renderer"):::renderer
        Q("Shadcn UI Renderer"):::renderer
    end

    %% Data Flow Connections
    U -->|"initiates"| A
    A -->|"calls"| C
    A -->|"calls"| D
    A -->|"calls"| E
    A -->|"calls"| F
    A -->|"calls"| G

    C -->|"processes"| H
    E -->|"processes"| H
    F -->|"processes"| I
    D -->|"authenticatesVia"| J

    H -->|"stores/fetches"| K
    I -->|"stores/fetches"| K

    H -->|"invokes"| L

    C -->|"returns"| A
    D -->|"returns"| A
    E -->|"returns"| A
    F -->|"returns"| A
    G -->|"returns"| A

    A -->|"previews"| M
    A -->|"previews"| N
    A -->|"previews"| O
    A -->|"previews"| P
    A -->|"previews"| Q

    %% Click Events
    click A "https://github.com/iamliulv/compoder/blob/main/app/layout.tsx"
    click A "https://github.com/iamliulv/compoder/blob/main/app/login/page.tsx"
    click A "https://github.com/iamliulv/compoder/blob/main/app/main/page.tsx"
    click B "https://github.com/iamliulv/compoder/tree/main/components/biz"
    click B "https://github.com/iamliulv/compoder/tree/main/components/ui"
    click C "https://github.com/iamliulv/compoder/tree/main/app/api/ai-core"
    click D "https://github.com/iamliulv/compoder/tree/main/app/api/auth"
    click E "https://github.com/iamliulv/compoder/tree/main/app/api/codegen"
    click F "https://github.com/iamliulv/compoder/tree/main/app/api/componentCode"
    click G "https://github.com/iamliulv/compoder/tree/main/app/api/config"
    click H "https://github.com/iamliulv/compoder/blob/main/app/services/codegen/codegen.service.ts"
    click I "https://github.com/iamliulv/compoder/blob/main/app/services/componentCode/componentCode.service.ts"
    click J "https://github.com/iamliulv/compoder/tree/main/lib"
    click K "https://github.com/iamliulv/compoder/tree/main/lib/db"
    click L "https://github.com/iamliulv/compoder/blob/main/app/api/ai-core/utils/aiClient.ts"
    click M "https://github.com/iamliulv/compoder/tree/main/artifacts/antd-renderer"
    click N "https://github.com/iamliulv/compoder/tree/main/artifacts/element-ui-plus-renderer"
    click O "https://github.com/iamliulv/compoder/tree/main/artifacts/html-renderer"
    click P "https://github.com/iamliulv/compoder/tree/main/artifacts/material-ui-renderer"
    click Q "https://github.com/iamliulv/compoder/tree/main/artifacts/shadcn-ui-renderer"

    %% Styles
    classDef user fill:#FFCC00,stroke:#000,stroke-width:2px;
    classDef frontend fill:#D0E6F6,stroke:#000,stroke-width:2px;
    classDef backend fill:#C3F3C3,stroke:#000,stroke-width:2px;
    classDef services fill:#F9F7C1,stroke:#000,stroke-width:2px;
    classDef database fill:#F6D6AD,stroke:#000,stroke-width:2px;
    classDef external fill:#F6A5A5,stroke:#000,stroke-width:2px;
    classDef renderer fill:#D5B9FF,stroke:#000,stroke-width:2px;
```
