# ntegrals/december architecture

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

- Interactive diagram: https://gitdiagram.com/ntegrals/december
- Repository: https://github.com/ntegrals/december

## Overview

##### Project type and purpose
- December is a full-stack AI-powered development environment that lets users generate, preview, edit, and export containerized Next.js apps from natural-language prompts.
- It comprises a Next.js frontend (with embedded Monaco editor and live preview), a TypeScript backend API, and orchestrates Docker containers and an LLM (OpenAI-compatible) service.

##### File structure
- Top-level:
- backend/ – Node.js (TypeScript) API, routes (chat, containers), services (docker, llm, file, export, package), utils, Dockerfile
- frontend/ – Next.js app (app directory), UI components (create, editor, projects), lib/backend/api.ts, config files for Bun/ESLint/Next.js, public assets
- config.ts – central config for baseUrl, apiKey, model, temperature
- start.sh – bootstraps config into backend, starts frontend on 3000 and backend on 4000
- Deployment:
- backend/src/Dockerfile – containerizes API
- uses Docker CLI to spin up ephemeral Next.js project containers for live preview and export
- Key patterns:
- API layer serving JSON and streaming LLM chat
- Micro-services style within a single backend process (services/docker.ts etc.)
- Componentized React UI, with a file manager and code editor in the browser

##### README
- Describes ports: frontend 3000, backend 4000
- Mentions Docker dependency and local API keys
- Highlights features: AI chat, code editor, live preview, project export

a. Main components
1. User’s Browser / Frontend (Port 3000)
– Next.js UI
– Monaco Editor + File Manager + Live Preview iframe
– Calls backend via REST/HTTP and WebSockets (for streaming chat/code)
2. Backend API Server (Port 4000)
– HTTP endpoints: /chat, /containers, /export, /package, /file
– Services:
- docker.ts – interfaces with Docker Engine via CLI or API
- llm.ts – calls external LLM provider (OpenAI et al.)
- file.ts – project file read/write
- export.ts – packages container to ZIP or tar
- package.ts – builds Next.js app inside container
3. Docker Engine
– Runs containerized Next.js apps generated by AI
– Provides live preview and project isolation
4. External LLM Service
– OpenAI-compatible API (Anthropic Sonnet-4 recommended)
5. Local File System
– Stores project source files, config, container artifacts
6. Config Store
– config.ts injected into backend to hold API keys and model settings

b. Relationships and interactions
- User → Frontend: clicks, types prompts, edits code
- Frontend → Backend:
– REST calls for chat prompts → streams LLM responses
– CRUD on project files
– Requests to build or export project
– Requests to spin up a preview container
- Backend → Docker Engine: create/start/stop containers, mount volumes
- Backend → LLM Service: send prompt, receive generated code or chat stream
- Backend → Local FS: read/write files for projects
- Frontend ← Live Preview Container: iframe or proxied HTTP to show running app

c. Architectural patterns and design principles
- Layered architecture: UI layer, API layer, service layer, infrastructure layer
- Service segregation: each domain (docker, llm, file, export) encapsulated in its own module
- Container-first deployment: every user-generated app runs in its own Docker container for isolation
- Streaming I/O: chat and code generation streamed through WebSockets or SSE
- Config-as-code: single config.ts propagated at startup

d. Technologies, frameworks, and libraries
- Frontend: Next.js 13 (“app” directory), React, TypeScript, Monaco Editor, PostCSS, ESLint, Bun (optional)
- Backend: Node.js, Express-style HTTP (via Bun or Node), TypeScript, Dockerfile, Docker Engine CLI
- LLM integration: OpenAI/Anthropic via HTTP
- Utilities: tsconfig.json, start.sh for orchestration, GitHub Actions (potential)

##### Final advice
- Be very detailed: include each backend service module and front-end feature group
- Flows: chat, code generation, container management, live preview, export
- Use consistent iconography for Docker, HTTP, WebSocket, file storage, and external APIs
- Important configs (e.g., config.ts) and startup script (start.sh) as part of the orchestration layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User’s Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer (Port 3000)"
        direction TB
        FEApp["Next.js Frontend"]:::frontend
        CodeEditor["Monaco Editor"]:::frontend
        FileManager["File Manager"]:::frontend
        LivePreview["Live Preview (Iframe)"]:::frontend

        subgraph "Chat UI Components"
            direction TB
            ChatInput["ChatInput"]:::frontend
            ChatMessage["ChatMessage"]:::frontend
            ChatSidebar["ChatSidebar"]:::frontend
        end

        subgraph "Dashboard UI"
            direction TB
            CreateDashboard["CreateDashboard"]:::frontend
            ProjectsPage["ProjectsPage"]:::frontend
            WorkspaceDashboard["WorkspaceDashboard"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer (Port 4000)"
        direction TB
        APIServer["Backend API Server"]:::backend

        subgraph "Routes"
            direction TB
            ChatRoute["/chat Endpoint"]:::backend
            ContainersRoute["/containers Endpoint"]:::backend
        end

        subgraph "Services"
            direction TB
            DockerService["Docker Service"]:::backend
            LLMService["LLM Service"]:::backend
            FileService["File Service"]:::backend
            ExportService["Export Service"]:::backend
            PackageService["Package Service"]:::backend
        end

        PromptUtil["Prompt Template"]:::backend
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        DockerEngine["Docker Engine"]:::external
        LivePreviewContainer["Live Preview Container"]:::external
        LLMAPI["External LLM Service"]:::external
        LocalFS["Local File System"]:::storage
        ConfigStore["Config Store (config.ts)"]:::orchestration
        StartupScript["Startup Script (start.sh)"]:::orchestration
    end

    %% Connections Frontend
    User -->|interacts with| FEApp
    FEApp -->|uses Editor| CodeEditor
    FEApp -->|uses FileManager| FileManager
    FEApp -->|renders| LivePreview
    FEApp -->|uses| ChatInput
    FEApp -->|uses| ChatMessage
    FEApp -->|uses| ChatSidebar
    FEApp -->|uses| CreateDashboard
    FEApp -->|uses| ProjectsPage
    FEApp -->|uses| WorkspaceDashboard

    FEApp -->|HTTP REST| APIServer
    FEApp -->|"WebSocket/SSE"| ChatRoute
    FEApp -->|HTTP REST| ContainersRoute
    FEApp -->|HTTP REST| FileService
    FEApp -->|HTTP REST| ExportService
    FEApp -->|HTTP REST| PackageService

    %% Backend connections
    APIServer -->|routes to| ChatRoute
    APIServer -->|routes to| ContainersRoute
    APIServer -->|calls| FileService
    APIServer -->|calls| ExportService
    APIServer -->|calls| PackageService

    ChatRoute -->|invokes| LLMService
    ContainersRoute -->|invokes| DockerService

    LLMService -->|HTTP API| LLMAPI
    DockerService -->|CLI/API| DockerEngine
    DockerEngine -->|runs| LivePreviewContainer
    LivePreviewContainer -->|iframe proxy| LivePreview

    FileService -->|read/write| LocalFS
    ExportService -->|writes| LocalFS
    PackageService -->|builds in| DockerEngine

    %% Orchestration
    StartupScript -->|injects| ConfigStore
    ConfigStore -->|provides| APIServer

    %% Click Events
    click FEApp "https://github.com/ntegrals/december/tree/main/frontend/src/app"
    click CodeEditor "https://github.com/ntegrals/december/blob/main/frontend/src/app/editor/CodeEditor.tsx"
    click CodeEditor "https://github.com/ntegrals/december/blob/main/frontend/src/app/editor/IDE.tsx"
    click FileManager "https://github.com/ntegrals/december/blob/main/frontend/src/app/editor/utils/FileManager.tsx"
    click LivePreview "https://github.com/ntegrals/december/blob/main/frontend/src/app/projects/components/LivePreview.tsx"
    click ChatInput "https://github.com/ntegrals/december/blob/main/frontend/src/app/create/components/ChatInput.tsx"
    click ChatMessage "https://github.com/ntegrals/december/blob/main/frontend/src/app/create/components/ChatMessage.tsx"
    click ChatSidebar "https://github.com/ntegrals/december/blob/main/frontend/src/app/create/components/ChatSidebar.tsx"
    click CreateDashboard "https://github.com/ntegrals/december/blob/main/frontend/src/app/create/components/CreateDashboard.tsx"
    click ProjectsPage "https://github.com/ntegrals/december/blob/main/frontend/src/app/projects/components/ProjectsPage.tsx"
    click WorkspaceDashboard "https://github.com/ntegrals/december/blob/main/frontend/src/app/projects/components/WorkspaceDashboard.tsx"
    click APIServer "https://github.com/ntegrals/december/blob/main/backend/src/index.ts"
    click DockerService "https://github.com/ntegrals/december/blob/main/backend/src/services/docker.ts"
    click LLMService "https://github.com/ntegrals/december/blob/main/backend/src/services/llm.ts"
    click FileService "https://github.com/ntegrals/december/blob/main/backend/src/services/file.ts"
    click ExportService "https://github.com/ntegrals/december/blob/main/backend/src/services/export.ts"
    click PackageService "https://github.com/ntegrals/december/blob/main/backend/src/services/package.ts"
    click ChatRoute "https://github.com/ntegrals/december/blob/main/backend/src/routes/chat.ts"
    click ContainersRoute "https://github.com/ntegrals/december/blob/main/backend/src/routes/containers.ts"
    click PromptUtil "https://github.com/ntegrals/december/blob/main/backend/src/utils/prompt.txt"
    click StartupScript "https://github.com/ntegrals/december/blob/main/start.sh"
    click ConfigStore "https://github.com/ntegrals/december/blob/main/config.ts"
    click APIServer "https://github.com/ntegrals/december/tree/main/backend/src/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef external fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFE0E0,stroke:#333,stroke-width:1px
```
