Codebook
An educational platform for new participants joining the Script alliance — a single-instance application that doubles as their first day-by-day reporting surface. Codebook is also the upstream ingress for daily updates flowing into emmie, which makes it a care-data corridor as well as a learning environment.
Tech Stack
- Backend: Laravel 12, PHP 8.4
- Frontend: Vue 3, TypeScript (mandatory — no Options API, no plain JavaScript), Vite. Two-bundle SPA:
client/(participant-facing default) +admin/at/beheer. - Database: MySQL, single-instance (distinct from emmie's DB-per-customer multi-tenancy).
- Hosting: Fly.io.
- Observability: Nightwatch in production (EU-Central-1; first war-room sighting of this tool) + Sentry. Two layers coexist.
- External integrations: emmie (day-update ingress, 9 endpoints over
X-Day-Update-Token); OpenAI (openai-php/client ^0.10.3, one call site); FontAwesome npm registry. - Default branch:
development - Ticket prefix:
CODE-XXXX(Kendo project_id 8 onkendo-scriptMCP server)
Compliance
Codebook carries the highest compliance burden after emmie: AVG (Dutch GDPR) mandatory + minors involved + NEN 7510 downstream gravity. The platform is used by real care participants — some of whom are minors — and the day-updates they submit flow into emmie, which is itself the most heavily regulated territory in the alliance. ISO 27001 is effectively inherited via downstream compliance gravity despite codebook sitting outside the selective script-development cert scope.
The compliance posture is actively being closed, not steady-state acceptable:
- Audit logging is structurally absent today. No
audit_logstable, noAuditLogmodel, no observers. AVG Article 15 right-of-access cannot be honored on a care-data ingress with active minors. Foundational AuditLog infrastructure (kendo ADR-0001 pattern with hash-chained tamper resistance) is gated to land as a 1-2 PR pre-campaign before the first Action extraction. cascadeOnDeleteon 9 User-FK migrations delegates AVG Article 17 right-to-erasure to MySQL FK behavior rather than explicit Action code. The cascade is structurally non-comprehensive — S3 objects, emmie-side data, OpenAI thread retention, and future audit logs all sit outside it. Migration toRESTRICTlands alongside the AuditLog foundation.- Backend-test infrastructure was deliberately absent until 2026-05-13. The "we do not write backend tests" stated policy is retired; replacement infrastructure is queued and gated on the Actions migration so the test boundary lands in the right place.
These gaps are documented honestly rather than hidden. The active development cycle is closing, not maintaining, the compliance posture.
Architecture Overview
Codebook is in transition. The target pipeline matches the war-room canonical shape:
Controller → FormRequest → DTO → Action → ModelThe current pipeline is Services-led: app/Services/ carries 4 Service classes mixing business logic with external-HTTP adapters. Commander disposition 2026-05-20 set the target architecture: Actions for business logic + Services restricted to external-request adapters. EmmieService and OpenAiService KEEP as external-request adapters; EditorService and PersonalMessageService MIGRATE to Actions. ~50 multi-write controller methods are queued for Action extraction.
Authorization: participant + mentor roles. Sanctum SPA-cookie session expected; full policy/gate/middleware posture is being verified.
No multi-tenancy. Single-instance application.
Frontend
The frontend is split into two SPAs (client/ for participants, admin/ at /beheer) plus shared and exercise modules. 25 business domains distributed across them follow the canonical vertical-slice shape:
resources/js/domains/[domain]/{components/, pages/, repository.ts, store.ts, transformer.ts}17 domains are uniform. 4 are Class A route-host variants. 3 are Class C drift candidates — dayupdate is inlined, kanbanboard is a 603-LOC bespoke surface, personalmessage is non-canonical. 12 domains lack pipeline test scripts; the highest-priority gaps are submission (974 LOC, PII) and user (1,048 LOC, AVG identity).
Two pre-Armory in-house systems sit at the foundation:
- A custom store/repository factory — sovereign-variant of
@script-development/fs-adapter-store. MIGRATE per Commander 2026-05-20 to align with kendo's adapter-store. - A custom
axioswrapper atapps/vue-services/http/index.ts— sovereign-variant of@script-development/fs-http. Engineer adoption campaign queued; CODE-0079 added a 60s interim timeout pending full migration.
Codebook's fs-packages adoption posture today: 0/10 by current state, queued for migration.
Educational payload: an exercises/ module ships 16 categories of authored content. This is the territory's distinctive surface — the platform is built around progressive participant learning, not just reporting.
Authentication
Sanctum SPA-cookie. Two role classes: participant and mentor. The deeper policy/gate posture is being mapped.
The day-update emmie token is separate from the codebook user session. Codebook authenticates the codebook user via Sanctum, then uses the user's stored 64-character opaque emmie_token (mirrored from emmie's clients.day_update_token) to act on behalf of the emmie client. No expiry, no rotation contract.
Key Decisions
| Decision | Status on Codebook |
|---|---|
| Audit Logging | Not Started — structurally absent today; foundational PR scheduled as 1-2 PR pre-campaign before first Action extraction |
| Cascade Deletion | Not Started — 9 cascadeOnDelete migrations; RESTRICT migration scheduled with the AuditLog foundation |
| AI Interaction Logging | Not Started — one OpenAI call site with no compliant logging; gated on the audit-logging foundation |
| Action Class Architecture | Migration-Pending — Services-led today; Engineer-tier migration campaign queued (180–240 expected days, 120–360 envelope) |
| FormRequest → DTO Flow | Migration-Pending — folds into the Actions migration |
| Explicit Model Hydration | Migration-Pending — 23 of 24 models use $fillable; User is the AVG-priority migration target |
| Resource Data Pattern | Migration-Pending — disposition reopened 2026-05-20 alongside Actions |
| Adapter-Store Pattern | Migration-Pending — sovereign-variant in use; MIGRATE to kendo's adapter-store per Commander 2026-05-20 |
| Canonical PHPStan Rules Package | Complete — adopted via PR #40 (CODE-0062), first ally outside founding territories |
| Page Integration Tests | Not Started — 113 frontend specs; 13 of 25 domains have pipeline coverage |
Tooling Stack
Following Jasper's 18-PR infrastructure wave (2026-05-17 → 2026-05-20), codebook now runs the most complete script-development tooling stack outside the founding territories: Pint + oxfmt + ESLint + PHPStan (with war-room rules) + Deptrac + Rector + a CI fan-out matrix with per-tool caches.
Quality gates fire as hooks — .githooks/ is wired automatically via composer install / npm install install-time side effects. Pint + oxfmt run on every Edit/Write through a PostToolUse hook; lint-staged runs on git commit; PHPStan + Deptrac run on git push. A SessionStart hook bootstraps dependencies by comparing lock-file mtime to marker files.
Distinctive ESLint posture (level-3 enforcement via eslint-plugin-project-structure): no localStorage, no .trim() / .toLowerCase() / .join() / .length directly (use the string-ts package), no magic numbers except -1, 0, 1, mandatory data-test attributes for DOM selection, it() over test() for spec cases. Frontend backend requests forbid try/catch — the HTTP service handles failures; try/catch is reserved for real runtime errors with a comment explaining why.
A vitest skill gate (PreToolUse) blocks .spec.ts edits unless /vue-vitest-testing has loaded within 120 minutes. The behavioral testing manifesto is baked into that skill: AAA, shallowMount default, mock every import, data-test selectors, flushPromises for async.
External Integrations
- emmie — 9-endpoint contract under
X-Day-Update-Tokenheader (/day-update-mentors,/day-update-schedules,/index-external-request,/store-external-request,/update-external-request,/destroy-external-request, plus auth-bootstrap and revocation). Per-call->timeout(10)per Architectural Principle #8. Contract authority lives on emmie (EMMIE-0042 shape, 2026-03-26 → 2026-04-02). - OpenAI (
openai-php/client ^0.10.3) — one call site. Prompt shape, user-data inclusion, and AVG considerations on third-party processing are being mapped. - FontAwesome npm registry — plaintext auth token committed at
.npmrc:3since 2023-06-02. Repo is private on GitHub; rotation requires third-party coordination. - Nightwatch + Sentry — production observability. PII scrubbing rules are being verified.
Collaboration
Codebook is sovereign. The Commander is the primary authority — war-room doctrine becomes codebook doctrine by default. Jasper (primarily a kendo developer at script-development) is the active ally developer, working tickets fast and using the kendo-script MCP surface (project_id 8) for filing. The platform is production-live with daily active users and is lightly maintained.
The documentation does not defer to ally decisions — this page and the territory briefing are the authority.