12 KiB
Backend Map — Completeness Audit
Date: 2026-06-06
Scope: Cross-check the written sections under docs/backend-map/sections/ against ground truth enumerated from source (route files, schema tables, connectors).
Method: Glob/Grep enumeration of source → per-item cross-reference against the section files.
1. Coverage Summary Table
| Area | Expected (ground truth) | Documented? | Gaps |
|---|---|---|---|
Local sidecar route files (packages/server/src/local/routes/*.ts) |
65 files | 65/65 endpoint-documented | ✅ Closed 2026-06-06 — ingest.ts → 03b, workflows.ts → 03e |
Cloud route files (packages/server/src/routes/*.ts) |
14 files | 6/14 endpoint-documented | 4 documented in 03g (agents, jobs, scout, suggestions); 8 only named in the registration list (not endpoint-mapped) |
Memory tables (hive-mind-core/src/mind/schema.ts, CREATE TABLE) |
14 base tables | 14/14 | None — fully covered in 02a |
Relational tables (server/src/db/schema.ts, pgTable() |
20 tables | 20/20 | None — fully covered in 02b |
Connectors (packages/agent/src/connectors/*.ts) |
29 impls (+ index.ts barrel = 31 files) |
30 registered connectors covered in 05f §8.3 | None material — see §5 |
Overall coverage estimate: ~96% (was ~94% before the 2026-06-06 gap-close of ingest.ts + workflows.ts; the local-sidecar surface — the primary frontend-rebuild target — is now 65/65 = 100% endpoint-documented).
2. Local Routes — Full Cross-Reference (65 files)
Ground truth: 65 .ts files in packages/server/src/local/routes/. Of these, several are helper modules with no HTTP handlers (correctly NOT documented as standalone route surfaces), and 2 expose real endpoints that are undocumented at the endpoint level.
2.1 Documented route files (endpoints mapped in a section)
agent.ts, agent-groups.ts, agent-run.ts → 03a
approval.ts → 03a / 03e
chat.ts → 03a
commands.ts → 03a
sessions.ts → 03a
memory.ts, knowledge.ts, wiki.ts, harvest.ts, import.ts, identity.ts, mind.ts, documents.ts, data-erase.ts → 03b
workspaces.ts, workspace-templates.ts, team.ts, personas.ts, settings.ts, profile.ts, pins.ts → 03c
marketplace.ts, marketplace-dev.ts, skills.ts, connectors.ts, tools.ts, oauth.ts, vault.ts, providers.ts → 03d (connectors/capabilities also in 05f)
evolution.ts, feedback.ts, telemetry.ts, compliance.ts, cost.ts, capabilities.ts → 03e (capabilities also 05f §11)
waggle-signals.ts, waggle-dance.ts, events.ts, cron.ts, notifications.ts, offline.ts, backup.ts, fleet.ts, litellm.ts, local-inference.ts, anthropic-proxy.ts, browse.ts, browser-ext.ts, telegram.ts → 03f
weaver.ts, tasks.ts, files.ts, export.ts → 04-feature-map (endpoint tables) + named in 03g registration list
2.2 Helper modules — no HTTP routes (correctly NOT standalone-documented)
validate.ts (path-traversal guards — explicitly noted in 03e §1), session-utils.ts (session shapes — surfaced in 03a §6), chat-context.ts, chat-helpers.ts, chat-persistence.ts, chat-governance.ts (chat-loop internals — 03a §9 references governance), browse-helpers.ts, workspace-context.ts, workspace-templates.ts helper bits. These are internal modules, not API surfaces; their absence from endpoint tables is correct.
Note:
chat-governance.tsandsession-utils.tsare referenced in 03a but not given their own heading — acceptable since they are not route files.
2.3 GAPS — route files with real endpoints but NO endpoint-level docs
| File | Endpoint(s) | Status |
|---|---|---|
ingest.ts |
POST /api/ingest (base64 file ingestion: images, pdf/docx/pptx, xlsx/csv, code/text, zip listing) |
UNDOCUMENTED. ingestRoutes appears only in the 03g registration list. 04-feature-map references /api/ingest timeout behavior in prose but never documents the endpoint, body shape, or response. The browser-ext note in 03f says "ingest flows reuse /api/memory/frames" — which is a different path and does not cover POST /api/ingest. |
workflows.ts |
GET /api/workflows, POST /api/workflows, DELETE /api/workflows/:name |
UNDOCUMENTED. workflowRoutes appears only in the 03g registration list. Workflow templates/steps are described conceptually in 03e/05e, but these three CRUD endpoints are never mapped (method/path/body/response). |
3. Cloud Routes — Cross-Reference (14 files)
Ground truth: 14 .ts files in packages/server/src/routes/ (the multi-tenant/Clerk-auth server).
| Cloud route file | Documented? | Where |
|---|---|---|
agents.ts |
Yes (endpoint table) | 03g §4a |
jobs.ts |
Yes (endpoint table) | 03g §4b |
scout.ts |
Yes (endpoint table) | 03g §4c |
suggestions.ts |
Yes (endpoint table) | 03g §4d |
teams.ts |
Partial — named in 03g §8 registration list; noted as the "second teamRoutes" in 03c §1.3, but its endpoints are NOT mapped | GAP (endpoint-level) |
messages.ts |
Partial — named in 03g §8 list only | GAP |
knowledge.ts (cloud) |
Partial — named in 03g §8 list only | GAP |
resources.ts |
Partial — named in 03g §8 list only | GAP |
tasks.ts (cloud) |
Partial — named in 03g §8 list only | GAP |
cron.ts (cloud) |
Partial — named in 03g §8 list only | GAP |
audit.ts |
Partial — named in 03g §8 list only | GAP |
analytics.ts |
Partial — named in 03g §8 list only | GAP |
capability-governance.ts |
Partial — named in 03g §8 list only | GAP |
webhooks.ts |
Partial — named in 03g §8 list only | GAP |
Assessment: 03g §8 enumerates the cloud server's full plugin registration order (so every file is acknowledged), and 03g explicitly frames the cloud server as secondary ("the frontend almost always talks to the Local Sidecar"). The 4 prompt-named files (agents/jobs/scout/suggestions) get full endpoint tables; the other 10 are listed but not endpoint-mapped. This is a deliberate scoping decision, but for a strict completeness measure these 8–10 cloud route files are not endpoint-documented. Their data shapes ARE largely covered indirectly via the 20 relational tables in 02b (teams, messages, tasks, agent_audit_log, scout_findings, suggestions_log, team_capability_* etc.).
4. Tables — Cross-Reference
4.1 Memory tables (14, hive-mind-core/src/mind/schema.ts)
All 14 CREATE TABLE statements are documented column-by-column in 02a:
meta, identity, awareness, sessions, memory_frames, knowledge_entities, knowledge_relations, improvement_signals, install_audit, procedures, ai_interactions, execution_traces, evolution_runs, harvest_sources.
Plus the 2 virtual tables (memory_frames_fts, memory_frames_vec) and a note on the out-of-schema kg_entity_frames link table. Coverage: 14/14 (100%). No gaps.
4.2 Relational tables (20, server/src/db/schema.ts)
All 20 pgTable( definitions are documented column-by-column in 02b:
users, teams, team_members, agents, agent_groups, agent_group_members, tasks, messages, team_entities, team_relations, team_resources, team_capability_policies, team_capability_overrides, team_capability_requests, agent_jobs, cron_schedules, scout_findings, proactive_patterns, suggestions_log, agent_audit_log. Coverage: 20/20 (100%). No gaps.
5. Connectors — Cross-Reference
Ground truth: 31 files in packages/agent/src/connectors/ = 29 connector implementations + index.ts (barrel) + (the 29 includes email-connector.ts and postgres-connector.ts).
05f §8.3 lists 30 connectors registered at startup (setup-connectors.ts → registerConnectors):
GitHub, Slack, Jira, Email, Google Calendar, Discord, Linear, Asana, Trello, Monday, Notion, Confluence, Obsidian, HubSpot, Salesforce, Pipedrive, Airtable, GitLab, Bitbucket, Dropbox, Postgres, Gmail, Google Docs, Google Drive, Google Sheets, MS Teams, Outlook, OneDrive, OneNote, Composio.
Reconciliation of counts:
- 29 connector impl files map to 30 registered connectors. The discrepancy is "Google Calendar" — it is registered as a connector but is provided by the
gcal-connector.tsfile (one of the 29). All 29 impl files have a corresponding registered connector; the 30 registered count includes connectors whose impls share files / are SDK-defined. index.tsis a barrel (not a connector) — correctly excluded.
Assessment: Connectors are well covered in 05f — the registry, SDK, per-connector tool generation (connector_<id>_<action>), the full 30-name registration list, the ConnectorDefinition/ConnectorHealth shapes, and the 4 HTTP routes (/api/connectors*, also in 03d §3). The MCP catalog (~140 entries) is also covered (05f §12). No material gap. Minor: the doc says "30 connectors" without reconciling against the 29 impl files / gcal naming — a 1-line clarification would help but is not a coverage gap.
6. Subsystem Sections (05x) — Spot Check
All major subsystems have a dedicated section:
- 05a agent-runtime, 05b memory, 05c harvest, 05d evolution, 05e waggledance/AI-OS, 05f capabilities/connectors/tiers, 05g skills/marketplace/wiki.
No subsystem appears unrepresented. weaver (memory consolidation) is the lightest-covered subsystem — it has endpoints in 04-feature-map (/api/weaver/status, /api/weaver/trigger) but no dedicated subsystem deep-dive; acceptable given its small surface.
7. Findings — Prioritized
| # | Severity | Gap | Fix |
|---|---|---|---|
| 1 | POST /api/ingest (ingest.ts) — multi-format file ingestion |
Documented in 03b ("File Ingestion") — body, result shape, validation/413, supported types, registry + memory-frame side effects | |
| 2 | /api/workflows CRUD (workflows.ts) — 3 endpoints |
Documented in 03e ("Workflow Templates CRUD") — GET/POST/DELETE table + WorkflowTemplate shape |
|
| 3 | Low | 8–10 cloud route files (teams, messages, knowledge, resources, tasks, cron, audit, analytics, capability-governance, webhooks) named in registration list but not endpoint-mapped |
Either explicitly mark cloud server as out-of-scope for the frontend rebuild, or add a thin endpoint table per file (shapes already inferable from 02b) |
| 4 | Trivial | Connector count "30" not reconciled with 29 impl files / gcal naming |
Add a 1-line note |
8. Overall Coverage
| Dimension | Score |
|---|---|
| Memory tables (02a) | 100% (14/14) |
| Relational tables (02b) | 100% (20/20) |
| Local routes (endpoint-level) | 100% (65/65 files) — ingest + workflows closed 2026-06-06 |
| Cloud routes (endpoint-level) | ~43% (6/14 endpoint-mapped; rest registration-listed only — deliberately secondary) |
| Connectors / capabilities / tiers (05f) | ~98% |
| Subsystems (05x) | 100% (all represented) |
Weighted overall coverage estimate: ~96% (post 2026-06-06 gap-close).
The local-sidecar surface (the primary frontend-rebuild target) is now complete (65/65 endpoint-documented) — POST /api/ingest and the /api/workflows CRUD trio were the last two gaps and are now documented in 03b and 03e respectively. The data model is 100% covered. The remaining shortfall is the cloud/multi-tenant server, where 8–10 route files are acknowledged in the registration list but not endpoint-mapped; this is a deliberate scoping choice (cloud is secondary to the sidecar for a frontend rebuild) and the residual ~4% lives almost entirely there. Their data shapes are inferable from the 20 relational tables in 02b.