feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,90 @@
+# C4 Architecture in Docusaurus — Mermaid Syntax Reference
+
+Mermaid (built into Docusaurus via `@docusaurus/theme-mermaid`) supports C4 diagrams natively.
+
+## L1 — C4Context
+
+```mermaid
+C4Context
+    title System Context — My Application
+
+    Person(user, "User", "Description of the human actor.")
+
+    System(mySystem, "My System", "What it does in one sentence.")
+
+    System_Ext(extA, "External System A", "Description")
+    System_Ext(extB, "External System B", "Description")
+
+    Rel(user, mySystem, "Uses")
+    Rel(mySystem, extA, "Fetches data", "REST API")
+    Rel(mySystem, extB, "Delivers output", "Webhook")
+```
+
+## L2 — C4Container
+
+```mermaid
+C4Container
+    title Container Diagram — My Application
+
+    Person(user, "User", "Description")
+
+    System_Boundary(mySystem, "My Application") {
+        Container(api, "API Service", "Python / FastAPI", "Handles requests.")
+        Container(worker, "Background Worker", "Python / Celery", "Async processing.")
+        ContainerDb(db, "Database", "PostgreSQL", "Stores data.")
+        Container(notifier, "Notifier", "Python", "Sends notifications.")
+    }
+
+    System_Ext(extA, "External System", "Description")
+
+    Rel(user, api, "Calls", "HTTPS")
+    Rel(api, worker, "Enqueues tasks", "Redis")
+    Rel(worker, db, "Reads/writes", "SQL")
+    Rel(notifier, extA, "Posts", "Webhook")
+```
+
+## L3 — C4Component
+
+```mermaid
+C4Component
+    title Components — API Service
+
+    Container_Ext(db, "Database", "PostgreSQL", "Stores data")
+    Container_Ext(worker, "Worker", "Celery", "Async tasks")
+
+    Container_Boundary(api, "API Service") {
+        Component(router, "Request Router", "FastAPI", "Routes HTTP requests.")
+        Component(authMiddleware, "Auth Middleware", "Python", "Validates tokens.")
+        Component(handler, "Request Handler", "Python", "Business logic.")
+        Component(repo, "Repository", "SQLAlchemy", "DB access layer.")
+    }
+
+    Rel(router, authMiddleware, "Passes request")
+    Rel(authMiddleware, handler, "Authenticated request")
+    Rel(handler, repo, "Queries data")
+    Rel(repo, db, "SQL", "TCP")
+    Rel(handler, worker, "Enqueues task", "Redis")
+```
+
+## Sidebar Structure for C4
+
+```ts
+// In sidebars.ts — recommended structure per app
+{
+  type: 'category',
+  label: 'C4 Architecture',
+  collapsed: false,
+  items: [
+    'applications/app-name/c4/context',     // L1
+    'applications/app-name/c4/containers',  // L2
+    'applications/app-name/c4/components',  // L3
+  ],
+},
+```
+
+## Tips
+
+- Each C4 level is a separate `.md` file under `docs/applications/<app>/c4/`
+- Add an `:::info C4 Model — Level N` admonition at the top of each page to explain what the level shows
+- For interactive diagrams (richer layout), use `draw.io` via `docusaurus-plugin-drawio` instead of Mermaid
+- Mermaid C4 is best for quick text-as-code diagrams; drawio is better for polished presentation diagrams