# composecraft/composecraft architecture

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

- Interactive diagram: https://gitdiagram.com/composecraft/composecraft
- Repository: https://github.com/composecraft/composecraft

## Overview

##### Project Type and Purpose
- Compose Craft is a full-stack web application built with Next.js (app router), TypeScript and React-Flow. It provides a GUI to create, edit, share and export Docker Compose files.
- It combines a React-based client UI, a Node.js/Next.js server API, a MongoDB database, and several external integrations (OAuth, email, telemetry).

##### Key Architectural Layers and Components
A. Client (Browser)
- Next.js pages/components under `app/` and `components/`
- React-Flow based playground for visual editing (`components/playground`)
- UI elements (buttons, tables, forms) under `components/ui`
- Global CSS, Tailwind, fonts, static assets in `app/globals.css` and `public/`

B. Server API (Next.js Node Runtime)
- API routes under `app/api/` (auth, compose, ping)
- Edge middleware (`middleware.ts`)
- Business logic and service calls implemented in `actions/` (e.g., `composeActions.ts`, `userActions.ts`)
- Data access and utilities under `lib/` (MongoDB connector, models, JWT auth, Brevo email, Directus)

C. Persistence
- MongoDB (collections: users, compositions, telemetry data)
- Models defined in `lib/models/*.ts`

D. External Services
- GitHub OAuth (login)
- Directus (optional CMS integration)
- Brevo (email notifications)
- Umami (self-hosted telemetry)

E. DevOps & Deployment
- Dockerfile + docker-compose.yml for container orchestration
- CI/CD workflows in `.github/workflows/` and `.gitlab-ci.yml`
- Environment variables for secrets, MongoDB URI, feature toggles

##### Relationships and Data Flow
1. User loads UI → Next.js SSR/SSR-stream renders pages + React hydrates.
2. In the playground: client interacts with React-Flow, updates local Zustand store (`store/`).
3. On save/share → client issues fetch to `POST /api/compose` → Next.js route handler invokes `composeActions`, validates/serializes YAML, stores record in MongoDB via `lib/mongodb`.
4. Share endpoint generates a public URL, stores metadata, possibly triggers Brevo email.
5. Auth flow: client ↔ `/api/auth/external` (GitHub OAuth) or `/api/auth/jwt` for token issuance → JWT stored in cookie/localStorage.
6. Telemetry events sent client-side to Umami (external).

##### Architectural Patterns & Principles
- Layered architecture: UI → API → Business Logic → Data Layer
- Single monorepo full-stack approach using Next.js “app” directory for server and client code.
- Separation of concerns:
- `components/` for UI
- `actions/` for use-case orchestration
- `lib/` for data access and integration utilities
- `store/` for client state (Zustand)
- Environment-driven feature flags (CORE_ONLY, DISABLE_TELEMETRY)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        UI_Pages["Next.js Pages & Layouts"]:::frontend
        Playground["React-Flow Playground"]:::frontend
        UI_Elements["UI Elements (Buttons, Tables, Forms)"]:::frontend
        Styles["Global Styles & Static Assets"]:::frontend
        Store["Zustand Store"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server (Node)"
        direction TB
        SSR["SSR & API Runtime"]:::backend
        API_Routes["API Routes (app/api/)"]:::backend
        Middleware["Edge Middleware"]:::backend
        Actions["Business Logic Actions"]:::backend
        Data_Access["Data Access & Utilities"]:::backend
    end

    %% Database
    MongoDB["MongoDB"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        GitHub["GitHub OAuth"]:::external
        Directus["Directus CMS"]:::external
        Brevo["Brevo Email"]:::external
        Umami["Umami Telemetry"]:::external
    end

    %% DevOps & Infra
    subgraph "DevOps & Deployment"
        direction TB
        Docker["Dockerfile & docker-compose.yml"]:::infra
        CI_CD["CI/CD Workflows"]:::infra
    end

    %% Connections
    UI_Pages -->|HTTP| SSR
    SSR -->|Hydrate| UI_Pages
    Playground -->|updates| Store
    Store -->|calls API| API_Routes
    API_Routes -->|invokes| Actions
    Actions -->|uses| Data_Access
    Data_Access -->|MongoDB Driver| MongoDB
    API_Routes -->|OAuth Flow| GitHub
    API_Routes -->|CMS Integration| Directus
    Actions -->|send email| Brevo
    Playground -.->|telemetry| Umami
    Docker -.-> SSR
    Docker -.-> MongoDB
    CI_CD -.-> Docker

    %% Click Events
    click UI_Pages "https://github.com/composecraft/composecraft/tree/main/app/"
    click Playground "https://github.com/composecraft/composecraft/tree/main/components/playground/"
    click UI_Elements "https://github.com/composecraft/composecraft/tree/main/components/ui/"
    click Styles "https://github.com/composecraft/composecraft/blob/main/app/globals.css"
    click Styles "https://github.com/composecraft/composecraft/tree/main/public/"
    click API_Routes "https://github.com/composecraft/composecraft/tree/main/app/api/"
    click Middleware "https://github.com/composecraft/composecraft/blob/main/middleware.ts"
    click Actions "https://github.com/composecraft/composecraft/tree/main/actions/"
    click Data_Access "https://github.com/composecraft/composecraft/tree/main/lib/"
    click Store "https://github.com/composecraft/composecraft/tree/main/store/"
    click Docker "https://github.com/composecraft/composecraft/tree/main/Dockerfile"
    click Docker "https://github.com/composecraft/composecraft/blob/main/docker-compose.yml"
    click CI_CD "https://github.com/composecraft/composecraft/tree/main/.github/workflows/"
    click CI_CD "https://github.com/composecraft/composecraft/blob/main/.gitlab-ci.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef database fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef infra fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
