Maintenance Overview
When and how to update each major subsystem, and how the FR→page traceability matrix signals when documentation itself must be updated.
Sixième Étoile is an 8-subsystem monorepo. Each subsystem has a different rate of change, a different cost to refactor, and a different documentation footprint. This section gives you the decision framework for each one.
The two questions
Before touching any subsystem, answer:
- Update or redevelop? Adding a strategy, a field, or a route is an update. Changing the core algorithm, replacing the ORM, or restructuring the DB schema across bounded contexts is a redevelopment.
- What documentation must change? Use the FR→page traceability matrix to identify which documentation pages are owned by the FRs your change touches.
Subsystem overview
| Subsystem | Source of truth | Typical change | Decision signal |
|---|---|---|---|
| Pricing engine | packages/api/src/services/ | Add strategy or rate | Configuration-first — no code if it can be a config |
| Data model | packages/database/prisma/schema/ | Add field or table | Prisma migration procedure |
| API routes | packages/api/src/routes/vtc/ | Add or change endpoint | Update OpenAPI spec + API reference |
| Realtime / SSE | packages/realtime | Add event type | Polling-fallback impact check |
| Apps (web, agency, tracking, driver) | apps/ | Change a screen | Screenshot regeneration required |
| Documentation platform | apps/docs | Add or update page | FR traceability gate (FR415) |
Configuration-first principle
Before writing new code in packages/api/src/services/, check whether the business requirement can be satisfied by a configuration change: a new zone multiplier, a fee catalog entry, or a pricing override. Code changes should be a last resort.
Recovery-first support principle
When operator access breaks after a deploy, verify the deployment secrets and the ensure-admin step before assuming the database is corrupt. The deploy pipeline now reapplies ADMIN_EMAIL and ADMIN_PASSWORD on every deployment, and FORCE_DB_RESET=true intentionally wipes and reseeds the database on the next init run. Use the emergency API reset route only when those recovery paths are unavailable or already exhausted.
Documentation update workflow
Every change that affects a user-facing screen or a documented FR triggers the documentation update workflow:
- Identify the FRs and registered screens your change touches.
- Run the traceability gate (FR415) check locally to confirm which documentation pages need updating.
- Update or create the documentation pages.
- Verify that both supported locales (EN, FR) have matching pages — the locale-parity gate (FR417) will fail the CI build otherwise.
- If screenshots change, regenerate them — the screenshot-drift gate (FR414) compares current screenshots to the committed baseline.
Per-subsystem guides
See also: Architecture overview · Pricing engine internals · Data Model