# Backend Reuse Alignment Roadmap

> **Historical reuse roadmap.** This draft is superseded by [`../PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](../PRODUCTION_READINESS_HANDOFF_ROADMAP.md) for active production-readiness execution. Backend platform/API drift is currently tracked there in P0.5, P2, P3, and P5.

Status: Draft
Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
Scope: `backend/`

# Goal

Keep the backend strongly product-specific for notes domain logic while maximizing reuse of ByteLyst shared packages and avoiding premature extraction of notes-specific code into common platform layers.

# Preserve As Product-Local

- [x] `notes` module remains local
- [x] `workspaces` module remains local
- [x] `note-relationships` module remains local
- [x] `note-tasks` module remains local
- [x] `note-artifacts` module remains local
- [x] `note-agent-actions` module remains local

# Shared Package Alignment

- [x] Continue using `@bytelyst/auth`
- [x] Continue using `@bytelyst/config`
- [x] Continue using `@bytelyst/cosmos`
- [x] Continue using `@bytelyst/datastore`
- [x] Continue using `@bytelyst/errors`
- [x] Continue using `@bytelyst/fastify-core`
- [x] Continue using `@bytelyst/logger`
- [x] Continue using `@bytelyst/testing`

# Dependency Notes

- [ ] Finalize backend contract decisions before broad web/mobile DTO cleanup
- [ ] Use this roadmap to define what must stay local before proposing any common-plat extraction
- [ ] Coordinate blob/extraction/MCP decisions with the platform/shared-services roadmap

# Phase B0 — Identity and Config Alignment

- [x] Keep `shared/product.json` as the backend identity source
- [ ] Ensure all persisted docs use the canonical product identity field
- [x] Review backend env schema for any duplicated or drifting product constants
- [x] Keep service URLs explicit for platform/extraction/MCP dependencies

# Phase B1 — Shared-Service Boundary Discipline

- [ ] Confirm no platform-service concern is being reimplemented locally
- [ ] Keep auth/identity concerns delegated to shared platform patterns
- [ ] Keep extraction logic delegated to `extraction-service`
- [ ] Keep blob authorization/upload patterns delegated to shared blob/platform flows
- [ ] Keep MCP orchestration compatible with shared `mcp-server`

# Phase B2 — Contract and DTO Hygiene

- [ ] Review backend response shapes used by web/mobile
- [ ] Identify DTO duplication across backend/web/mobile
- [ ] Introduce a repo-local shared contracts layer only if duplication becomes costly
- [ ] Do not move notes-specific contracts to common platform unless another product clearly needs them

# Phase B3 — Hardening

- [ ] Add route behavior tests using Fastify `inject()`
- [ ] Add repository behavior tests
- [ ] Add cross-entity tests for notes + relationships/tasks/artifacts/agent actions
- [ ] Review request tracing and error behavior against workspace standards
- [ ] Replace raw stdout/stderr startup output with shared logger patterns if practical

# Guardrails

- Do not move notes-specific modules into `platform-service`
- Do not create shared abstractions that only benefit this one product
- Do not over-generalize the notes domain into common platform prematurely

# Done When

- [ ] backend remains clearly product-specific
- [ ] shared package usage is explicit and clean
- [ ] backend contracts are stable enough for web/mobile integration
- [ ] backend quality is improved without architectural drift