Visuals & Diagrams — Tracking and Specifications
This document lists every visual or diagram that should be added to the existing documentation. Each entry includes enough detail (type, content, labels, relationships) that an engineer can produce the diagram in one sitting without needing to re-read the underlying doc. The goal is fast creation, no back-and-forth.
The team has indicated visuals are easier to absorb than narrative — so this is a high-leverage doc improvement.
How to use this doc
For each suggested visual:
- Pick a P0 or P1 item from the list (sorted by impact within each doc).
- Read the What to show description — it lists every box, label, arrow, and color that should appear.
- Render it using the suggested tool (default: Mermaid in the markdown itself).
- Insert the diagram into the target doc at the specified section.
- Cross out the row here, or remove it from this doc when complete.
When all P0 items are done, the highest-leverage half of the work is finished.
Default to Mermaid wherever possible:
- Renders natively in GitHub, GitLab, VS Code, Bitbucket, and most modern markdown viewers.
- Lives inside the markdown file, so it versions with the doc.
- No image files to manage, no broken links, no rebuild step.
- Sufficient for: flowcharts, sequence diagrams, state diagrams, ER diagrams, gantt charts, simple topologies.
Use external tools for:
- Heat maps / radar charts — Mermaid doesn't do these well. Use Excalidraw (free, web-based, exportable to PNG/SVG) for the maturity-model visuals.
- Architecture topology with rich icons — draw.io / diagrams.net (free, has AWS/GCP icon libraries). Export as SVG for crispness in dark/light mode.
- Quick whiteboard-style sketches — Excalidraw is the lightest weight.
Embed produced PNG/SVG files in the audit tree (someli-doc/audit/someli-api/images/) and reference them with relative paths.
Priority legend
- P0 — explains a complex multi-component flow that text struggles with; in a frequently-read doc.
- P1 — useful complement to text; in a moderately-read doc.
- P2 — nice-to-have polish; in a reference doc.
1. README.md (index)
| ID |
Type |
Where |
Priority |
What to show |
| R-1 |
Doc map |
At the top, before the tables |
P2 |
A simple cluster diagram grouping the docs into the same five sections the README already has (Architecture & Design / AI & Content / Inventories / Sub-systems / Cross-Cutting / Operations / Strategy). Each cluster contains the doc names as nodes. Helps a new joiner orient in one glance. Mermaid: use flowchart TD with subgraphs per cluster. |
2. architecture-overview.md (P0 doc — read by everyone)
| ID |
Type |
Where |
Priority |
What to show |
| A-1 |
System topology |
Top of doc, replacing the textual "Server layering" |
P0 |
Boxes for: Web client (out of scope), API process (Express + Socket.IO), Worker fleet (~108 PM2 jobs), MySQL RDS, S3 (×2 buckets), External services (Bedrock, Vertex, OpenAI, Paddle, SendGrid, Slack, social platforms). Arrows show: HTTP traffic into API; API ↔ MySQL; API ↔ S3; API ↔ external services; Workers ↔ MySQL (polling); Workers ↔ S3; Workers ↔ external services. Use Mermaid flowchart LR. |
| A-2 |
Request lifecycle (middleware chain) |
"Middleware stack" section |
P0 |
Vertical sequence: Incoming HTTP → express-session → express-fileupload → express.json (150 MB) → static routes → /health → passport.initialize → passport.session → cors() → route handlers → (response). Include annotations marking known issues (no rate limit, CORS open, hardcoded session secret). Mermaid: flowchart TD. |
| A-3 |
Module organization (current vs target) |
"Routes mounted in server.js" section |
P1 |
Two side-by-side flowcharts. Current: server.js → routes/{routes,auth,social,paddle,partnerAuth} (showing routes.js as 21k lines and auth.js as 24k lines, called out visually with size). Target (modular monolith): server.js → modules/{identity,content,publishing,analytics,billing,notifications}/index.ts → internals. Helps the team see the destination shape. Mermaid: two flowchart TD blocks side-by-side. |
| A-4 |
DB access patterns |
"Database" section |
P1 |
A small flow showing the three current DB drivers (mysql, mysql2, sync-mysql), the centralized App.db object, and which files use which pattern. Annotate with the count of callers per pattern (sync-mysql: 127, mysql2: 53, mysql: 1). Mermaid: flowchart LR. |
3. authentication.md (P0 doc — every new joiner reads this)
| ID |
Type |
Where |
Priority |
What to show |
| AUTH-1 |
Token issuance sequence |
"Token Lifecycle" section |
P0 |
Sequence diagram: Client → POST /auth/login → server validates credentials → generate JWT → AES-encrypt JWT → return encrypted token → client stores it. Use Mermaid sequenceDiagram. Annotate with the env vars used at each step (JWT_SECRET_KEY, AES key). |
| AUTH-2 |
Token validation per request |
"Authorization Checks" section |
P0 |
Sequence diagram: Client → request with header x-access-token: <encrypted> → middleware (middlewares/auth.js) → AES-decrypt → JWT verify → attach userId, role, accountId to req → handler. Show the failure case (401 with plain string body). Mermaid sequenceDiagram. |
| AUTH-3 |
OAuth flow (generic, applies to all 6 providers) |
"OAuth Flows" section |
P0 |
Sequence diagram: User → /social/{provider} → Passport redirect → Provider login page → Provider callback → /social/{provider}/callback → server exchanges code for token → store in tMemberAuth → redirect user to APP_URL. Mermaid sequenceDiagram. |
| AUTH-4 |
Dual auth path comparison |
"Authentication" intro |
P1 |
Small flowchart showing middlewares/auth.js (Passport JWT, returns 401) vs methods.js (custom AES-only decryptData, returns 403). Helps explain the readiness-doc concern about consolidating these. Mermaid flowchart LR. |
4. configuration.md
| ID |
Type |
Where |
Priority |
What to show |
| CFG-1 |
Config loading flow |
"Loading Mechanism" section |
P2 |
Simple flow: .env file → dotenv → conf.js → exported object → consumed by 892 callers. Annotate that dashboard/conf.js does the same thing separately. Mermaid flowchart LR. |
| CFG-2 |
Env-var → subsystem map |
After the variable tables |
P2 |
Bipartite graph: env var groups (DB, AWS, GCP, OAuth, AI, Paddle, etc.) on one side; consuming subsystems (HTTP API, content pipeline, RAG, billing, etc.) on the other. Helps when troubleshooting "which feature breaks if I unset X." Mermaid flowchart LR. |
5. content-pipeline.md (P0 doc — describes the most complex flow)
| ID |
Type |
Where |
Priority |
What to show |
| CP-1 |
End-to-end content lifecycle |
Top of doc |
P0 |
Big flowchart showing the journey of a single piece of content: User intent → CGEN (text gen) → DGEN (design render) → DPGEN (post variant) → TIV (validation) → MCC/TCH (correction loops) → UCL (branding) → scheduled → published → insights collected. Each stage is a node with the responsible job file in parentheses. Use distinct colors for "queue states" vs "transformation steps." Mermaid flowchart LR or flowchart TD. |
| CP-2 |
Job-status state machine |
"Status states" section |
P0 |
State diagram: 0 (pending) → 1 (processing) → 2 (success) or 3 (retry) → if retry → 1 again → finally 4 (failed) or 2 (success). Annotate transitions with what triggers them. Mermaid stateDiagram-v2. |
| CP-3 |
Job-type chain |
"Type reference" section |
P0 |
Directed graph showing which job types enqueue which others: e.g., RTCON (rephrase + translate) → enqueues RGEN (regenerate). All chains visible: brand-positioning → objective → recommended-subjects → CGEN → ... Helps understand the cascade. Mermaid flowchart LR. |
| CP-4 |
A worker's tick loop |
"Performance characteristics" section |
P1 |
Sequence diagram of a single tick: cron fires → check isOnProcess lock → SELECT ... LIMIT 1 from tJobs → mark row status=1 → run logic (AI call, S3, etc.) → update result → release lock. Annotate where polling pressure on MySQL happens. Mermaid sequenceDiagram. |
6. data-model.md (P0 reference doc)
| ID |
Type |
Where |
Priority |
What to show |
| DM-1 |
High-level ER diagram (core entities) |
Top of doc, replacing the existing ASCII or as a complement |
P0 |
ER diagram with the ~15 most important tables: tMember, tDefaultAccount, tAccounts, tUserLibrary, tMedia, tUploads, tLibrary, tJobs, tBrandPositioning, tObjective, tRecommendedSub, tSubscriptions, tEmailSchedule, tSPosts, tSPostInsights. Show foreign-key relationships. Mermaid erDiagram. |
| DM-2 |
Identity cluster |
New subsection |
P1 |
Smaller ER focused on tMember + tDefaultAccount + tAccounts + tMemberAuth + tRoleType + sessions. Mermaid erDiagram. |
| DM-3 |
Content cluster |
New subsection |
P1 |
Smaller ER focused on tUserLibrary + tMedia + tUploads + tLibrary + tBrandPositioning + tObjective + tRecommendedSub + tRephrased_Translated_Content + tCategories. Mermaid erDiagram. |
| DM-4 |
Job & queue cluster |
New subsection |
P1 |
Smaller ER focused on tJobs + tEmailSchedule + tCorporateLogs + the various status flags. Helpful for operational debugging. Mermaid erDiagram. |
| DM-5 |
Module ownership map |
After all ER diagrams |
P1 |
Overlay-style visual showing which conceptual module (identity / content / publishing / etc.) "owns" each table. Best done as a colored table or matrix rather than a graph. Helps for the modular-monolith refactor. Could be a markdown table with color coding via emoji or a heat-map image. |
7. deployment.md (P0 doc)
| ID |
Type |
Where |
Priority |
What to show |
| DEP-1 |
Three-path topology |
Top of doc, replacing the ASCII "At a glance" block |
P0 |
Three side-by-side environment diagrams: Dev (Lightsail/EC2 + nginx + PM2 + GHA/Jenkins), UAT (ECR → Fargate tasks → uapi.someli.ai), Prod (EC2 + PM2, undocumented). Each shows the deploy mechanism arrow and the runtime topology. Use draw.io with AWS icon set for clarity. Export as SVG. |
| DEP-2 |
Fargate "one image, many tasks" |
"Path 3" section |
P0 |
Visual of single ECR image → multiple Fargate task definitions, each with different CMD overrides (server.js, job_facebook_publish.js, job_paddle_webhook_handler.js, etc.). One image at the top, fanning out to N tasks below. Mermaid flowchart TD with the image as the parent. |
| DEP-3 |
nginx → Node → DB request path |
"Application Server" section |
P1 |
Simple horizontal flow: HTTPS → ALB → nginx (port 80) → Node (port 3000) → MySQL. Annotate body limits (nginx: 100 MB; Node: 150 MB; mismatch is a known issue). Mermaid flowchart LR. |
| DEP-4 |
CI pipeline conflict |
"Issues & Risks §6.1" |
P1 |
Visual showing both Jenkins and GHA wired to the same dev_api branch, both deploying. Helps make the "two CI systems racing" finding obvious. Mermaid flowchart LR. |
8. error-handling.md
| ID |
Type |
Where |
Priority |
What to show |
| ERR-1 |
Response shapes today |
"Where the Pattern Breaks" section |
P1 |
Comparison flow: Same request hitting four different endpoints, returning four different shapes (envelope success, envelope error, raw 4xx JSON, plain string). Helps the frontend team see why client-side handling has to be defensive. Mermaid flowchart LR with branches. |
| ERR-2 |
Where errors can originate |
"CRUD Layer" section |
P2 |
Stack diagram: HTTP request → middleware (can throw) → route handler (try/catch or not) → action layer (cb(null) on error) → DB driver (raw err). Each layer annotated with what happens when it errors. Mermaid flowchart TD. |
9. logging-observability.md
| ID |
Type |
Where |
Priority |
What to show |
| LOG-1 |
Current state vs target state |
Top of doc |
P0 |
Side-by-side comparison. Current: console.log → stdout → PM2 captures → file on host → pm2 logs + grep. Target: structured logger → OTel SDK → collector → vendor (Datadog/Loki/CloudWatch) + metrics + traces + alerts → on-call. Mermaid: two flowchart LR blocks. |
| LOG-2 |
Healthcheck flow |
"Healthcheck Endpoints" section |
P2 |
Simple sequence: Load balancer → /health → Express handler → JSON response (no DB) and Load balancer → /db-health → Express handler → DB query → JSON response. Mermaid sequenceDiagram. |
10. notifications.md
| ID |
Type |
Where |
Priority |
What to show |
| NOT-1 |
Email queue flow |
"Delivery model" section (already has ASCII art — convert to a real diagram) |
P0 |
Convert the existing ASCII art into Mermaid sequenceDiagram: Route handler → INSERT into tEmailSchedule (status=0) → job_send_mail polls every 60s → reads pending rows → calls SendGrid API → updates status=1 (sent) or 2 (failed). Annotate that this decouples user-facing flow from email delivery. |
| NOT-2 |
Slack alert flow |
"Slack" section |
P2 |
Simple flow: Job (e.g., job_color_check.js) → catches result/error → posts to Slack channel C05TS9AHBH6. Annotate that the token is hardcoded (security concern). Mermaid flowchart LR. |
11. realtime-events.md
| ID |
Type |
Where |
Priority |
What to show |
| RT-1 |
Socket.IO event broadcast (already exists as ASCII) |
"Event Flow" section |
P2 |
Convert the existing ASCII sequence diagram into a real Mermaid sequenceDiagram showing Client A → Server (io.emit('update', msg)) → all clients (including A). Same content, better visual fidelity. |
12. security.md
| ID |
Type |
Where |
Priority |
What to show |
| SEC-1 |
Defense in depth |
Top of doc |
P0 |
Onion / concentric-circles diagram. From outside in: WAF → ALB → CORS → helmet → rate limit → auth → input validation → app code. Color each layer green/yellow/red based on current state (most are red — gaps). Best done in Excalidraw and exported as PNG. |
| SEC-2 |
Secrets handling: where secrets live today |
"Secrets Management" section |
P1 |
Two-column table-as-diagram. Left: secrets that are correctly in .env (DB password, AWS keys, etc.). Right: secrets that are hardcoded (Slack token, Polotno key, session secret). Visualize the imbalance. Markdown table with emoji indicators is fine. |
| SEC-3 |
Middleware stack with security responsibilities |
"Middleware Stack — Order Matters" section |
P1 |
Vertical chain showing the middleware order, with security responsibilities annotated at each layer (or marked "missing"). Mermaid flowchart TD. |
13. agents-and-ai.md
| ID |
Type |
Where |
Priority |
What to show |
| AG-1 |
Agent orchestration sequence |
"Onboarding Flow" section (already has ASCII) |
P0 |
Convert the existing ASCII flow into a Mermaid sequenceDiagram: User → ConversationAgent → InputParserAgent (parse free text) → ConversationAgent (collect info) → ResearchAgent (Google Search + Gemini) → ConversationAgent → ProfileAgent (final draft) → User (approve/reject). Show the streaming callbacks where they apply. |
| AG-2 |
Conversation state machine |
"ConversationAgent" section |
P1 |
State diagram showing: greeting → collecting personal info → collecting company info → research-in-flight → profile-draft-shown → approval-pending → completed (or rejected → back to draft). Mermaid stateDiagram-v2. |
14. user-specific-ai.md
| ID |
Type |
Where |
Priority |
What to show |
| USAI-1 |
Common worker tick pattern |
"Common Pattern" section (already has ASCII) |
P0 |
Convert existing ASCII flow to Mermaid flowchart TD: cron tick → SELECT pending row → fetch AI parameters → invoke model → success: UPDATE status=1, OR failure: UPDATE status=2 (retry) or 3 (give up). |
| USAI-2 |
Brand → objective → recom-subjects dependency chain |
"Ordering" subsection |
P0 |
Directed graph: tCompany_Website_Info (filled in) → brand_positioning_ai → tBrandPositioning approved → objective_ai → tObjective approved → recom_subjects_ai → tRecommendedSub. Each step gates the next via the isAi*_created flags. Mermaid flowchart LR. |
| USAI-3 |
Status flow for these jobs |
"Status flow" section |
P1 |
State diagram: 0 (pending) → 1 (success) OR 0 → 2 (retry on first error) → 3 (give up after second error). Plus the queue-driven workers' 0 → 1 → 2 (done) / 4 (failed). Mermaid stateDiagram-v2. |
15. dashboard-analytics.md
| ID |
Type |
Where |
Priority |
What to show |
| DASH-1 |
Production vs dev mounting |
"Production: Mounted Into the Main App" + "Local Development: Standalone Mode" |
P1 |
Two side-by-side topologies. Production: main server.js → mounts dashboard/routes/index.js at /auth → uses parent's con. Local: dashboard/server.js on port 6001 → uses dashboard/mock/routes.js. Mermaid two flowchart LR blocks. |
| DASH-2 |
Cron services data flow |
"Cron Services" section |
P1 |
Flowchart: Social platforms → fetch via job_post_insights.js (every 30s) → tSPostInsights → job_growth_insights.js (every 12h) computes deltas → dashboard endpoints read both. Mermaid flowchart LR. |
| ID |
Type |
Where |
Priority |
What to show |
| MED-1 |
Media pipeline overview (already has ASCII) |
"Overview" section |
P0 |
Convert ASCII to Mermaid: Sources (user upload, stock APIs, Polotno JSON, AI-generated) → Processing (Sharp resize/JPEG, FFmpeg frame, Polotno render) → Storage (S3 primary + S3 secondary). Add labels for ~36 Sharp callers, ~49 Polotno instantiations to call out the duplication problem. |
| MED-2 |
Polotno render flow |
"Polotno" section |
P0 |
Sequence diagram: Job → createInstance({key}) → spawns Chromium → jsonToImageBase64(json) → returns PNG base64 → uploaded to S3. Annotate the cold-start cost (~100 MB Chromium per call, no pooling). Mermaid sequenceDiagram. |
| MED-3 |
S3 dual-bucket strategy |
"AWS S3 — Dual-Bucket Setup" section |
P1 |
Visual of two buckets (us-west-2 primary, us-west-1 secondary) with content categories assigned to each. Helps onboarding engineers know "where does X live." draw.io with AWS S3 icons. |
17. rag-pipeline.md
| ID |
Type |
Where |
Priority |
What to show |
| RAG-1 |
Two RAG implementations side by side |
"Overview" section |
P0 |
Comparison diagram. Left (in-memory): account_id S3 prefix → list files → parse (PDF/DOCX/CSV/TXT) → chunk → Bedrock Cohere embed → in-memory cosine → top-k chunks. Right (Cloud RAG): pre-indexed Vertex corpus (corpusName) → cloudRagResult call → Vertex AI does retrieval + LLM in one shot → response. Mermaid two flowchart TD blocks. |
| RAG-2 |
getAiParametersFunction as the dispatcher |
"getAiParametersFunction" section |
P1 |
Flow showing: Caller passes (languageId, ...) → reads tLanguageModels + tTrainingData → returns model config + filled-in prompt → caller decides (Vertex Cloud RAG vs in-memory RAG vs no retrieval). Mermaid flowchart TD. |
18. API-inventory.md
| ID |
Type |
Where |
Priority |
What to show |
| API-1 |
Endpoint distribution by route file |
Top of doc |
P2 |
Bar chart: routes/auth.js (~24k lines, X endpoints), routes/routes.js (~21k lines, Y endpoints), routes/social.js (Z), etc. Helps visualize where the surface area lives. Render in any chart tool, embed as PNG. |
| API-2 |
Auth-required vs public endpoints |
New subsection |
P2 |
Pie or stacked bar showing the split: % requiring JWT, % requiring Bearer (methods.js), % public. Reinforces the dual-auth-path finding. Render as PNG. |
19. Integration-inventory.md
| ID |
Type |
Where |
Priority |
What to show |
| INT-1 |
External services topology |
Top of doc |
P0 |
Big map: someli-api in the center, surrounded by external services grouped by category (AWS: S3, Bedrock, Secrets Manager; GCP: Vertex, GCS; AI: OpenAI; Social: FB, IG, LI, TT, TW; Billing: Paddle; Email: SendGrid; Notifications: Slack; Stock images: Pexels, Pixabay, Unsplash). Each line annotated with which subsystem uses it. draw.io with vendor icons works well. |
| INT-2 |
Cross-region data flow |
New subsection |
P0 |
Geographic-style diagram showing the flow between regions: app in us-west-2 ↔ MySQL in us-west-1 ↔ media S3 in us-west-1 ↔ Bedrock in us-east-1 ↔ Vertex AI in us-central1. Annotate latency / egress cost concerns at each hop. Helps justify the "consolidate to one region" recommendation. draw.io. |
20. jobs-inventory.md
| ID |
Type |
Where |
Priority |
What to show |
| JOB-1 |
Job count by category |
"Summary by Category" section |
P1 |
Bar chart: each of the 16 categories with its job count. Visual makes it obvious that publishing + media + AI dominate. Render as PNG. |
| JOB-2 |
Job-type cascade graph |
"Job Type Codes" section |
P0 |
Directed graph showing how job types enqueue each other: CGEN/UGEN feed DGEN; DGEN feeds DPGEN; DPGEN feeds TIV; TIV feeds MCC/TCH; etc. Helps explain why fixing one job's bug ripples downstream. Mermaid flowchart LR. |
| JOB-3 |
PM2 process tree |
"PM2 Configuration" section |
P1 |
Tree diagram of the ~39 PM2 apps grouped by category. Mermaid flowchart TD with subgraphs per category. |
21. enterprise-readiness.md (P0 strategic doc)
| ID |
Type |
Where |
Priority |
What to show |
| ER-1 |
Maturity radar chart |
§3 Maturity Model |
P0 |
Radar / spider chart with 14 axes (the 14 pillars). Three series plotted: current (red), 12-mo target (yellow), 24-mo target (green). Visually shows the gap. Use Excalidraw or a chart library — render as PNG/SVG and embed. |
| ER-2 |
Roadmap gantt |
§6 Roadmap |
P0 |
Gantt chart showing Phase 0a (this week) → Phase 0 (months 0–3) → Phase 1 (months 3–9) → Phase 2 (months 9–18) → Phase 3 (months 18+, optional). Each phase has its workstreams as bars. Mermaid gantt. |
| ER-3 |
Polyglot target architecture |
§5.1 Language & Runtime |
P0 |
Topology diagram: HTTP API (Node.js + TypeScript, single deployment unit) ←HTTPS← clients; Job queue (NATS / Temporal / BullMQ-Redis) in the middle; Worker fleet (Go or JVM, multiple processes) ←consumes← queue. Show that the queue is the seam. Mermaid flowchart LR. |
| ER-4 |
Modular monolith target structure |
§5.2 Architecture Pattern |
P0 |
Tree diagram showing the proposed src/modules/{identity,content,publishing,analytics,billing,notifications} + src/platform/ layout. Annotate each module with its public-API entry point (index.ts) and the lint-enforced boundary. Mermaid flowchart TD. |
| ER-5 |
"What gets cut" decision matrix |
§6.5 What gets cut |
P1 |
A table / matrix listing the explicitly-rejected technologies (multi-region active-active, Kubernetes, event sourcing, GraphQL, polyglot persistence, per-module DBs, event-driven internal communication, anti-corruption layers) with the team-size threshold or trigger that would change the answer. Markdown table. |
| ER-6 |
Risk register heatmap |
§7 Risk Register |
P1 |
2D heatmap with Likelihood (1–4) on one axis and Impact (1–4) on the other. Each risk plotted as a dot at its (likelihood, impact) coordinate, color-coded by severity. R-1 through R-23 numbered on the dots. Excalidraw or a chart library. |
| ER-7 |
Standards compliance matrix |
§8 Standards Compliance |
P1 |
A grid: standards (OWASP API Top 10 items, Twelve-Factor factors, SOC 2 criteria) as rows; status (C / P / N / NA) shown with color cells. Already partly tabular in the doc — convert to a colored matrix image for impact. Excalidraw. |
22. maturity-model.md
| ID |
Type |
Where |
Priority |
What to show |
| MAT-1 |
Pillar source diagram |
§4 Origin of the Pillars |
P1 |
Bipartite graph: external frameworks (TOGAF, DORA, OWASP, ISO 27001, AWS Well-Architected, FinOps Foundation, Google SRE Book, etc.) on one side; the 14 pillars on the other. Lines connecting each pillar to its source(s). Helps reviewers see the legitimacy of the model. Mermaid flowchart LR. |
| MAT-2 |
Level transition curve |
§3 The 1–5 Scale |
P2 |
Simple vertical bar showing approximate "calendar time to transition" between levels: L1→L2 (1 quarter), L2→L3 (2 quarters), L3→L4 (1 year), L4→L5 (rare). Helps calibrate expectations. Render as PNG. |
23. getting-started.md
| ID |
Type |
Where |
Priority |
What to show |
| GS-1 |
Setup flowchart |
Top of doc |
P0 |
Vertical flowchart: prerequisites → clone → Node 20.18.1 (NVM) → yarn install → MySQL setup (3 options) → schema bootstrap → .env → npm run dev → smoke test → ✅. Each step links to the relevant section. Mermaid flowchart TD. |
| GS-2 |
Local-dev environment topology |
"First successful run" section |
P1 |
Simple topology: Developer's machine running Node + Sharp + Puppeteer → MySQL (local Docker or shared) → S3/Bedrock/Vertex (real, via AWS/GCP creds). Annotate which can be skipped in dev. Mermaid flowchart LR. |
24. first-deployment.md
| ID |
Type |
Where |
Priority |
What to show |
| FD-1 |
New-environment AWS topology |
§2 AWS account prerequisites |
P0 |
Detailed AWS topology: VPC with public/private subnets in 2 AZs, ALB in public, Fargate tasks (API + workers) in private, RDS Multi-AZ, S3 buckets (×2 regions), ECR, Secrets Manager, NAT Gateways. Use draw.io with AWS icon set. Export as SVG. |
| FD-2 |
Build & deploy sequence |
§3 Build the container image + §5 Task definitions |
P0 |
Sequence diagram: Developer → docker build → docker push to ECR → update ECS task definition with new image SHA → ECS rolls out new tasks → ALB health check → traffic shifts. Mermaid sequenceDiagram. |
| FD-3 |
Task-definition pattern (one image, many tasks) |
§5.2 Worker task definitions |
P0 |
Same as DEP-2 (deployment.md). Either reuse or duplicate — one ECR image fanning out to N task definitions, each with a different command. Mermaid flowchart TD. |
| FD-4 |
First-deploy verification flow |
§8 First-deploy verification |
P1 |
Vertical checklist as a flowchart: each verification step in §8 as a box, with arrows to "next check" or "back to fix." Mermaid flowchart TD. |
25. verify-markers.md
No diagrams suggested. This is a checklist; visuals would not add value.
Summary by priority
| Priority |
Count |
Estimated total effort (one engineer working from these specs) |
| P0 |
25 |
3–4 days |
| P1 |
20 |
2–3 days |
| P2 |
7 |
1 day |
| Total |
52 |
~7–8 days of focused work |
Even just the 25 P0 visuals would dramatically improve the docs — that's ~3–4 days of work for the team's most-read sections.
Suggested order of work
- Day 1 — All P0 Mermaid diagrams in
architecture-overview.md, authentication.md, content-pipeline.md, data-model.md (core conceptual docs every engineer reads).
- Day 2 — All P0 Mermaid diagrams in
deployment.md, getting-started.md, first-deployment.md (operational docs every new joiner reads).
- Day 3 — All P0 Mermaid diagrams in subsystem docs (
agents-and-ai.md, user-specific-ai.md, media-processing.md, rag-pipeline.md, notifications.md, logging-observability.md).
- Day 4 — P0 visuals that need external tooling:
enterprise-readiness.md radar chart and gantt, Integration-inventory.md topology, security.md defense-in-depth onion. These are higher-effort because they need draw.io / Excalidraw / chart-libraries.
- Days 5–7 — All P1 visuals.
- Day 8 — P2 polish.
After Day 4 the docs are dramatically better. Days 5–8 are diminishing returns.
Maintenance
Once a visual is added:
- Cross out or remove the corresponding row in this doc.
- If the underlying topic changes (new env added, new module created, new external service integrated), update the diagram in the same PR as the code change.
- Mermaid diagrams version with the doc, so this is just discipline — no separate tooling.
When this doc is empty, every doc has the visuals it needs. At that point the doc can be deleted.
- All the docs in this folder
- README.md — index