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.
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 all three locales (EN, FR, ES) 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