How lumither/nocturne works
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