# danshaders/kege-by-danshaders architecture

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

- Interactive diagram: https://gitdiagram.com/danshaders/kege-by-danshaders
- Repository: https://github.com/danshaders/kege-by-danshaders

## Overview

##### Project type and purpose
- This is a full-stack web application (“kege-by-danshaders”).
- Frontend: a React/TypeScript single-page application under `ui/`.
- Backend: a high-performance C++ HTTP/FCGI service under `api/`, talking to PostgreSQL.
- Deployment: containerized services orchestrated via `docker-compose.yml`, using Nginx as a reverse proxy and Postgres for persistence.
- Additional components: Protobuf definitions under `proto/` for API schema; developer tools in `tools/`.

##### File structure
- Top-level directories:
- `api/`: CMake-based C++ service, with headers in `api/include/async`, `api/include/routes`, implementations in `api/src/`.
- `ui/`: React/TSX code, CSS, static HTML entry point, build scripts in `build.mjs`.
- `proto/`: `.proto` files defining messages and service contracts.
- `meta/`: Dockerfiles, CMake fragments, Nginx config, Postgres init scripts—deployment manifests.
- `tools/`: standalone CLI utilities (e.g., `diff-proto`, `sql-typer`) built with CMake.
- Configuration: `docker-compose.yml` ties services together.
- Build: multiple CMake projects for the API and tools.

a. Main components
- Frontend SPA (browser)
- Nginx reverse proxy (container)
- C++ API service (FastCGI)
- PostgreSQL database
- Optional tooling/CI containers (for codegen or migrations)
b. Relationships and data flow
1. User interacts with the SPA → HTTP(S) requests
2. Nginx routes frontend asset requests to the static server or proxies API requests to FastCGI
3. API service processes requests via an async event loop, executes SQL (via `async/pq`), applies business routes (`api/include/routes/*.h`)
4. API returns JSON over FastCGI → Nginx → Browser
5. Database persists and retrieves data; init scripts under `meta/postgres/` run at container startup
6. Protobuf definitions under `proto/` document the API schema (used for code generation or cross-service communication)
c. Architectural patterns and design principles
- Asynchronous, non-blocking I/O with an event loop (`libev-event-loop`)
- Modular route handlers (each REST endpoint in `api/routes/`)
- Separation of concerns: transport (FastCGI), business logic (routes), data access (async/pq)
- SPA-style client with unidirectional data flow and React component hierarchy
- Containerization and infrastructure as code (Docker, Compose, Nginx, Postgres)
d. Key technologies and frameworks
- C++17 (CMake, coroutines via `async/coro.h`)
- FastCGI (via `fcgx.h`)
- libev for event handling
- PostgreSQL driver (`async/pq`)
- React + TypeScript (bundled via `ui/build.mjs`)
- Protobuf for API contracts
- Nginx for TLS, proxying, static hosting

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        Browser["Browser"]:::client
        SPA["React SPA"]:::frontend
    end

    Browser -->|"HTTP(S) request"| Nginx
    Browser -->|"API calls"| Nginx
    Nginx -->|"serves assets"| Browser

    %% Docker Containers
    subgraph "Docker Compose"
        direction TB
        subgraph "Containers"
            direction TB
            Nginx["Nginx Reverse Proxy"]:::infra
            subgraph "API Container"
                direction TB
                APISvc["API Service (C++/FCGI)"]:::service
                subgraph "Internal Components"
                    direction TB
                    HTTP["HTTP Layer"]:::service
                    EventLoop["Async Event Loop"]:::service
                    Routes["Route Dispatch"]:::service
                    DataLayer["Data Layer (async/pq)"]:::service
                end
            end
            Postgres["PostgreSQL 13"]:::db
        end
    end

    %% Data Flows
    Nginx -->|"FastCGI"| HTTP
    HTTP --> EventLoop
    EventLoop --> Routes
    Routes --> DataLayer
    DataLayer -->|"SQL"| Postgres
    Postgres -->|"Result"| DataLayer
    DataLayer -->|"JSON"| Nginx
    Nginx -->|"JSON"| Browser

    %% Protobuf Definitions
    subgraph "Protobuf Definitions"
        direction TB
        Proto["proto/*.proto"]:::proto
    end
    Proto --> APISvc
    Proto --> SPA

    %% Developer Tools
    subgraph "Developer Tools"
        direction TB
        DiffProto["diff-proto"]:::tools
        SQLTyper["sql-typer"]:::tools
    end
    Proto --> DiffProto
    Proto --> SQLTyper

    %% Click Events
    click SPA "https://github.com/danshaders/kege-by-danshaders/tree/master/ui/"
    click SPA "https://github.com/danshaders/kege-by-danshaders/tree/master/ui/src/"
    click SPA "https://github.com/danshaders/kege-by-danshaders/blob/master/ui/index.html"
    click SPA "https://github.com/danshaders/kege-by-danshaders/blob/master/ui/build.mjs"
    click SPA "https://github.com/danshaders/kege-by-danshaders/tree/master/ui/css/"
    click SPA "https://github.com/danshaders/kege-by-danshaders/blob/master/ui/package.json"
    click SPA "https://github.com/danshaders/kege-by-danshaders/blob/master/ui/tsconfig.json"

    click APISvc "https://github.com/danshaders/kege-by-danshaders/tree/master/api/"
    click APISvc "https://github.com/danshaders/kege-by-danshaders/blob/master/api/CMakeLists.txt"
    click HTTP "https://github.com/danshaders/kege-by-danshaders/tree/master/api/include/"
    click Routes "https://github.com/danshaders/kege-by-danshaders/tree/master/api/include/routes/"
    click Routes "https://github.com/danshaders/kege-by-danshaders/tree/master/api/routes/"
    click DataLayer "https://github.com/danshaders/kege-by-danshaders/tree/master/api/src/"
    click APISvc "https://github.com/danshaders/kege-by-danshaders/blob/master/api/src/main.cc"

    click Nginx "https://github.com/danshaders/kege-by-danshaders/blob/master/meta/nginx/nginx.conf"
    click Nginx "https://github.com/danshaders/kege-by-danshaders/blob/master/meta/api.dockerfile"
    click Nginx "https://github.com/danshaders/kege-by-danshaders/blob/master/docker-compose.yml"

    click Postgres "https://github.com/danshaders/kege-by-danshaders/tree/master/meta/postgres/"
    click Postgres "https://github.com/danshaders/kege-by-danshaders/blob/master/meta/postgres/init-script.sh"
    click Postgres "https://github.com/danshaders/kege-by-danshaders/blob/master/meta/postgres/db.sql"

    click Proto "https://github.com/danshaders/kege-by-danshaders/tree/master/proto/"

    click DiffProto "https://github.com/danshaders/kege-by-danshaders/tree/master/tools/diff-proto/"
    click SQLTyper "https://github.com/danshaders/kege-by-danshaders/tree/master/tools/sql-typer/"

    classDef client fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef frontend fill:#b3d9ff,stroke:#333,stroke-width:1px;
    classDef infra fill:#d9d9d9,stroke:#333,stroke-width:1px;
    classDef service fill:#d0f0c0,stroke:#333,stroke-width:1px;
    classDef db fill:#fff2cc,stroke:#333,stroke-width:1px;
    classDef proto fill:#e6ccff,stroke:#333,stroke-width:1px;
    classDef tools fill:#ffddb3,stroke:#333,stroke-width:1px;
```
