# Backend Roadmap

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

# Phase B0 — Scaffold

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

# Phase B1 — Core Domain

## Modules

- [x] `notes`
- [x] `workspaces`

## Tasks

- [x] Define note schemas
- [x] Define workspace schemas
- [x] Implement repositories
- [x] Implement routes
- [x] Add auth and workspace scoping rules
- [x] Add CRUD tests

# Phase B2 — Supporting Domain

## Modules

- [x] `note-relationships`
- [x] `note-tasks`
- [x] `note-artifacts`
- [x] `note-search` or search endpoints inside existing modules

## Tasks

- [x] Add linking APIs
- [x] Add artifact metadata APIs
- [x] Add task extraction persistence model
- [ ] Define attachment/blob references
- [ ] Expand integration tests across entities

# Phase B3 — Agent Domain

## Module

- [x] `note-agent-actions`

## Tasks

- [x] Define proposal vs applied change model
- [x] Define approval state transitions
- [x] Define audit event shape
- [x] Add idempotency approach for agent writes
- [x] Add request/workflow correlation support
- [x] 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

- Dependencies are not installed yet, so typecheck/test/build verification remains pending.
- 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