Someli API — Documentation Index
Technical documentation for the someli-api backend. Each document is generated from codebase analysis and reflects the current state of the system.
Architecture & Design
| Document |
Description |
| Architecture Overview |
Server layering, startup sequence, route patterns, middleware stack, database access patterns, helper modules |
| Content Pipeline |
End-to-end flow from content creation through AI generation, design rendering, branding, validation, scheduling, and publishing |
| Authentication & Security |
Token lifecycle (JWT + AES), OAuth flows for 6 providers, partner auth, role model, authorization checks |
| Real-Time Events |
Socket.IO initialization, events, broadcasting patterns, current scope |
AI & Content
| Document |
Description |
| Conversational AI Agents |
Onboarding agents in agents/: ConversationAgent, InputParserAgent, ResearchAgent, ProfileAgent (Gemini-driven, synchronous, in-request) |
| User-Specific AI Jobs |
PM2 daemons in user_specific_contents_ai/: brand positioning, objectives, recommended subjects, translation, rephrasing |
| RAG Pipeline |
Two RAG paths — in-memory (Bedrock Cohere + cosine) and Cloud (Vertex AI managed corpora); plus getAiParametersFunction model selection |
Inventories
| Document |
Description |
| API Inventory |
~728 endpoints across 6 route files with method, path, auth, and description |
| Jobs Inventory |
All background workers across job_*.js, user_specific_contents_ai/, dashboard/services/, and standalone generators; with type-code mapping and known config discrepancies |
| Integration Inventory |
33 external service integrations with packages, config keys, and operations |
| Data Model |
~140+ database tables with columns, relationships, FK mappings, and ER diagram |
Sub-systems
| Document |
Description |
| Dashboard Sub-Application |
Semi-independent analytics app: 22 endpoints, 3 cron services, mock layer for local dev |
| Media Processing |
S3 dual-bucket setup, Sharp, FFmpeg, Polotno design rendering, stock images (Pexels/Pixabay/Unsplash) |
| Notifications |
Slack alerts (operational) and SendGrid email via dynamic templates and the tEmailSchedule queue |
Cross-Cutting Concerns
| Document |
Description |
| Error Handling & Response Patterns |
Standard envelope, where the pattern breaks, status code conventions, CRUD-layer error swallowing |
| Logging & Observability |
Current state (console.log everywhere), healthchecks, pm2 logs recipes, gaps |
| Security (Beyond Authentication) |
CORS, helmet, rate limiting, body limits, input validation, secrets, sessions |
Operations
| Document |
Description |
| Getting Started |
Bootstrapping a developer machine from zero — prerequisites, install, .env, smoke tests, common gotchas |
| First Deployment |
Standing up a brand-new environment from zero — AWS prerequisites, IAM, ECS/Fargate task definitions, DNS, OAuth callbacks |
| VERIFY Markers |
Index of every [VERIFY] block in the runbooks — context, guidance, and owner per marker. Shrinks as gaps are filled |
| Visuals & Diagrams Tracking |
Per-doc list of suggested diagrams with content specs detailed enough to render without re-reading the source doc. Shrinks as visuals are added |
| Deployment & DevOps |
Ongoing deploys: Docker, nginx, CI/CD (GitHub Actions + Jenkins), PM2 process management, branch strategy, three-path topology |
| Configuration Reference |
~72 environment variables grouped by service with required/optional flags |
| Dependencies Inventory |
All 91 npm packages with usage counts, status (active/light/unused/deprecated), removal candidates, license / CVE / size verifications |
These are full-picture documents derived from the component subtrees.
| Document |
Description |
| TDD Report |
The master Technical Due Diligence report — executive-ready, board-consumable, customer-presentable. Currently DRAFT v0.1 (API populated; web client + admin dashboard pending) |
| Doc Tree Structure |
Documentation organization principles, target tree, migration plan |
Strategy
| Document |
Description |
| Enterprise Readiness Assessment |
Auditor's view of the platform: maturity model, gap analysis per pillar, 24-month modernization roadmap, risk register, compliance matrix |
| Maturity Model & Methodology |
Why the maturity model was chosen, where the 14 pillars come from, level-by-level grading rubric, how to apply ratings |
Practices & Discipline
| Document |
Description |
| Engineering Charter |
The 12 commitments — what the team is signed up to. Leadership-signed |
| Engineering Practices |
Operational catalog: code, PR, test, architecture, security, observability, DB, dependency, and doc rules — each with rationale, enforcement, and escape valve |
| Definition of Done |
Per-PR checklist with the rationale behind each item |
| PR Template Reference |
Content for .github/PULL_REQUEST_TEMPLATE.md (to be installed when write access is available) |
Quick Links