# lumither/nocturne architecture

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

- Interactive diagram: https://gitdiagram.com/lumither/nocturne
- Repository: https://github.com/lumither/nocturne

## Overview

##### Project Type and Purpose
- This is a full‑stack personal website (“Nocturne”) combining a Next.js frontend with a Rust‑based backend, an API gateway, and a Python CLI client.
- The frontend serves pages, blog listings and markdown content. The backend handles blog data storage, markdown parsing, scheduling, and database operations. The gateway exposes a unified HTTP API. The CLI client assists with content generation or management.

##### File‑Structure Analysis
- Top level:
- frontend/  → Next.js app (TypeScript, pages, components, CSS, tailwind)
- backend/   → Rust workspace:
– macros/    → custom derive/log macros
– markdown/  → markdown parsing, front‑matter utilities
– server/    → main HTTP server, modules (blog, scheduler), SQL schema & queries
- gateway/   → Rust-based API gateway (main.rs)
- client/    → Python CLI with templates for post generation
- container/, dev.compose.yaml, prod.compose.yaml → Dockerfiles & Compose for dev/prod
- Notice: server/src/modules/blog splits into API handlers (get_post, get_page_count) and components (check_update, consistency_guard, rag). Scheduler under server/src/scheduler.
- Config/build: Cargo.toml (Rust workspaces), package.json (frontend), requirements.txt (client).

##### README Insights
- Purpose: personal website with blog posts stored externally (content repo).
- Tech stack: Next.js (frontend), Rust (backend & gateway), Python (CLI), Docker for deployment.

##### Main Components & Their Interactions
a. Components
1. Next.js Frontend
- Hosts UI pages (blog list, post pages, about, search, friends).
- Uses built‑in API routes or fetch.ts to call HTTP API.
2. API Gateway (Rust)
- Single entrypoint for frontend → backend services.
- Handles routing, logging, authentication (if any), CORS.
3. Blog Server (Rust)
- Exposes HTTP endpoints (e.g., /api/blog/get_post, get_page_count).
- Uses SQL queries for PostgreSQL/SQLite.
- Initializers: database, logger, misc.
- Scheduler sub‑component runs recurring tasks (e.g., update check).
4. Markdown Library & Custom Macros (Rust)
- markdown/ parses and renders content; macros/ provides codegen/log helpers.
5. Database
- Relational DB (Postgres or SQLite) managed via Docker Compose.
- stores blog posts, tags, categories.
6. CLI Client (Python)
- Generates or manages posts from templates, updates front‑matter.
7. External Services
- GitHub API (for HomePageActivities).
- CDN (for static assets), Analytics (if used).

b. Interactions & Data Flow
- Browser → Next.js UI
- UI → Gateway (HTTP REST/JSON)
- Gateway → Blog Server (HTTP forwarding)
- Blog Server → Database (SQL queries)
- Blog Server ↔ Markdown library/macros for content parsing
- Scheduler tasks (internal to Blog Server) periodically run to refresh content
- CLI → local file system & API to push new content

##### Architectural Patterns & Design Principles
- Microservices‑style separation: Gateway vs. Server
- Modular Rust code: workspace crates (macros, markdown, server)
- Clear layering: API handlers → business components → data access (SQL)
- Next.js’s SSR and API routes separation
- Docker‑first deployment for reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Layer
    Browser["Browser"]:::user
    Nextjs["Next.js Web App"]:::user
    Browser -->|"HTTP/HTTPS"| Nextjs
    click Nextjs "https://github.com/lumither/nocturne/tree/master/frontend/"

    %% API Layer
    Gateway["Rust API Gateway"]:::compute
    Nextjs -->|"HTTP/JSON"| Gateway
    click Gateway "https://github.com/lumither/nocturne/blob/master/gateway/src/main.rs"

    %% Service Layer
    subgraph "Rust Blog Server" 
        direction TB
        ServerInit["Initialization Modules"]:::compute
        ServerAPI["API Handlers"]:::compute
        ServerBiz["Business Components"]:::compute
        ServerSched["Scheduler"]:::compute
        ServerMD["Markdown Library & Macros"]:::compute
        ServerDAL["Data Access Layer"]:::compute

        ServerAPI -->|"calls"| ServerBiz
        ServerBiz -->|"uses"| ServerDAL
        ServerAPI -->|"parses"| ServerMD
        ServerBiz -->|"parses"| ServerMD
        ServerSched -->|"async tasks"| ServerBiz
        ServerSched -.->|"SQL"| ServerDAL

        click ServerInit "https://github.com/lumither/nocturne/tree/master/backend/server/src/init/"
        click ServerAPI "https://github.com/lumither/nocturne/tree/master/backend/server/src/modules/blog/api/"
        subgraph "Components" 
            direction TB
            CheckUpd["Check Update"]:::compute
            ConsGuard["Consistency Guard"]:::compute
            RAG["RAG Component"]:::compute
            CheckUpd -->|"SQL"| ServerDAL
            ConsGuard -->|"SQL"| ServerDAL
            RAG -->|"SQL"| ServerDAL
            click CheckUpd "https://github.com/lumither/nocturne/tree/master/backend/server/src/modules/blog/components/check_update/"
            click ConsGuard "https://github.com/lumither/nocturne/tree/master/backend/server/src/modules/blog/components/consistency_guard/"
            click RAG "https://github.com/lumither/nocturne/tree/master/backend/server/src/modules/blog/components/rag/"
        end
        ServerBiz --> Components
        click ServerSched "https://github.com/lumither/nocturne/tree/master/backend/server/src/scheduler/"
        click ServerMD "https://github.com/lumither/nocturne/tree/master/backend/markdown/"
        click ServerDAL "https://github.com/lumither/nocturne/blob/master/backend/server/src/modules/blog/schema.sql"
    end

    Gateway -->|"HTTP/JSON"| RustServer["Rust Blog Server"]

    %% Database
    DB["PostgreSQL DB"]:::datastore
    RustServer -->|"SQL"| DB

    %% CLI Client
    CLI["Python CLI Client"]:::devtool
    CLI -->|"HTTP/JSON"| Gateway
    CLI -->|"FS Templates"| CLI
    click CLI "https://github.com/lumither/nocturne/tree/master/client/cli/"

    %% External Services
    GH["GitHub API"]:::compute
    RustServer -->|"HTTPS"| GH

    %% Infrastructure
    subgraph "Infrastructure (Docker Compose)" 
        direction TB
        DevCompose["dev.compose.yaml"]:::datastore
        ProdCompose["prod.compose.yaml"]:::datastore
        DevCompose --> Nextjs
        DevCompose --> Gateway
        DevCompose --> RustServer
        DevCompose --> DB
        ProdCompose --> Nextjs
        ProdCompose --> Gateway
        ProdCompose --> RustServer
        ProdCompose --> DB
        click DevCompose "https://github.com/lumither/nocturne/blob/master/dev.compose.yaml"
        click ProdCompose "https://github.com/lumither/nocturne/blob/master/prod.compose.yaml"
    end

    %% Styles
    classDef user fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef compute fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef devtool fill:#DDA0DD,stroke:#333,stroke-width:1px;
```
