learning_ai_notes/docs/roadmaps/02_BACKEND_ROADMAP.md

Backend Roadmap

Status: In Progress Parent: docs/ROADMAP.md Stack: Fastify 5 + TypeScript ESM + Zod + Cosmos

Phase B0 — Scaffold

• Create backend package structure
• Wire @bytelyst/config
• Wire @bytelyst/auth
• Wire @bytelyst/errors
• Wire @bytelyst/cosmos
• Wire @bytelyst/logger
• Wire @bytelyst/testing
• Wire @bytelyst/fastify-core
• Add /health
• Establish route registration pattern
• Establish container registration pattern

Phase B1 — Core Domain

Modules

• notes
• workspaces

Tasks

• Define note schemas
• Define workspace schemas
• Implement repositories
• Implement routes
• Add auth and workspace scoping rules
• Add CRUD tests

Phase B2 — Supporting Domain

Modules

• note-relationships
• note-tasks
• note-artifacts
• note-search or search endpoints inside existing modules

Tasks

• Add linking APIs
• Add artifact metadata APIs
• Add task extraction persistence model
• Define attachment/blob references
• Expand integration tests across entities

Phase B3 — Agent Domain

Module

• note-agent-actions

Tasks

• Define proposal vs applied change model
• Define approval state transitions
• Define audit event shape
• Add idempotency approach for agent writes
• Add request/workflow correlation support
• Add tests for approval and agent write paths

Phase B4 — Hardening

• Query/index review
• Performance tuning
• Fallback behavior review
• Typecheck passes
• Test suite passes
• Build passes
• Health/readiness verification passes

Progress Notes

• 2026-03-10 — Initial backend scaffold created under backend/.
• Added:
  • package.json
  • tsconfig.json
  • .env.example
  • shared/product.json
  • shared backend bootstrap files under src/lib/
  • notes and workspaces modules
  • note-relationships module
  • note-tasks module
  • note-artifacts module
  • note-agent-actions module
  • explicit /notes/search endpoint
  • starter server and route tests
• Current data model split:
  • notes partitioned by /workspaceId
  • workspaces partitioned by /userId
  • supporting containers registered for relationships, tasks, artifacts, and agent actions

Open Questions

• Should notes remain partitioned by /workspaceId or move to /userId with secondary workspace filtering?
• Should workspace membership remain embedded in the workspace document for MVP or move to a dedicated membership container?
• What minimum search contract should land in B2 versus be folded into the notes module first?

Blockers

• Backend verification has advanced, but the current automated route coverage is still mostly registration-focused rather than deep API-behavior or cross-entity integration coverage.
• The product identity is still provisional and may require small follow-up renames before wider integration.

Deferred

• Blob-backed attachment reference hardening
• Approval workflow UX and enforcement hardening
• Audit/idempotency/correlation validation across integrated mutating flows

High-Collision Areas

• shared route registration files
• shared auth hooks
• shared config files
• container registration files

Done When

• Backend supports all MVP note workflows
• Agent write paths are auditable
• Shared platform integrations are wired cleanly
• Build/test/typecheck are stable