# CraftCode Academy — Project Build Log

**Document type:** Engineering build log  
**Project:** CraftCode Academy  
**Owner:** HelsaGrace Okporho  
**Documented:** 16 November 2026  
**Primary evidence:** source repository, database migrations, QA book v1.20, local build and browser verification  
**Companion document:** [PROJECT_CASEBOOK.md](./PROJECT_CASEBOOK.md)

> This is an engineering record, not a diary. Every entry below is grounded in a file, a migration, a test or a captured interface. Where the repository and the written project record disagree, both positions are stated.

---

## 1. Identity and scope

| Field | Detail |
|---|---|
| **Application** | CraftCode Academy |
| **Repository** | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode` |
| **Product type** | Public academy site, enrolment pipeline, learner platform, administrator console |
| **Frontend** | React 19 single-page application built with Vite |
| **Backend** | Supabase (PostgreSQL, Auth, Row-Level Security, Storage) |
| **Hosting** | Netlify (SPA redirects, security headers) |
| **Live release** | `https://craftcode-academy.netlify.app`, revisions 1.1–1.5, commit `abd9d36` |
| **Working tree** | Revisions 1.6–1.19 application changes plus revision 1.20 test/documentation changes; uncommitted and undeployed |
| **Migrations** | 19 files; 001–012 applied, 013–018 content repairs, 019 applied and verified 2026-11-16 |
| **Database tables** | 39, all with row-level security enabled |
| **Database functions** | 47 security-definer or helper functions |
| **Automated tests** | 10 test files; 94 tests, all passing after the 1.20 selector fix |

The scope of this build log is the application code and its operational behaviour. Product rationale lives in the casebook. Deployment history and release state are recorded honestly because the working tree is substantially ahead of the live site.

---

## 2. Stack and toolchain

### 2.1 Runtime dependencies

| Package | Version | Role |
|---|---|---|
| `react` | 19.3.1 | UI runtime |
| `react-dom` | 19.3.1 | DOM renderer |
| `react-router-dom` | 7.18.5 | Client-side routing |
| `@supabase/supabase-js` | 2.119.0 | Auth, database, storage |
| `lucide-react` | 1.73.0 | Icon system |
| `@fontsource-variable/fraunces` | 5.3.0 | Display typeface |
| `@fontsource-variable/inter` | 5.3.0 | Sans fallback |
| `@fontsource-variable/jetbrains-mono` | 5.3.0 | Mono typeface |
| `@fontsource/manjari` | 5.3.0 | Primary body typeface |

### 2.2 Build and quality dependencies

| Package | Version | Role |
|---|---|---|
| `vite` | 8.3.6 | Dev server and production build |
| `typescript` | 7.0.2 | Type checking |
| `tailwindcss` | 3.4.17 | Utility styling |
| `postcss` | 8.5.6 | CSS pipeline |
| `autoprefixer` | 10.4.21 | Vendor prefixes |
| `vitest` | 5.1.0 | Test runner |
| `@testing-library/react` | 16.3.0 | Component tests |
| `@testing-library/jest-dom` | 7.0.1 | DOM assertions |
| `jsdom` | 31.0.1 | Test environment |
| `oxlint` | 1.90.0 | Lint |

### 2.3 Scripts

```json
{
  "dev": "vite",
  "build": "tsc -b && vite build",
  "typecheck": "tsc -b",
  "lint": "oxlint",
  "test": "vitest run",
  "test:watch": "vitest",
  "preview": "vite preview"
}
```

The build is type-checked before bundling. There is no separate compile step and no server runtime in the frontend.

### 2.4 Environment configuration

The client reads only two public values, `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`, through `src/lib/config.ts`. When they are absent, `src/lib/supabase.ts` sets the client to `null` and throws `BackendNotConfiguredError` on use, with a message that tells the operator to configure the environment. It does not silently fall back to fabricated data.

No service-role key is imported into the frontend. This is a stated project invariant in `AGENTS.md`, and the code respects it: the only Supabase client is constructed with the anon key.

---

## 3. Repository map

```
craftcode/
├── src/
│   ├── App.tsx                  Route tree and guards
│   ├── components/
│   │   ├── admin/               Admin tables, dialogs, editors
│   │   ├── auth/                Auth screens and frames
│   │   ├── brand/               Identity components
│   │   ├── enrolment/           Registration, confirmation, status lookup, founding places
│   │   ├── illustrations/       SVG artwork
│   │   ├── layout/              Public header, footer, mobile navigation
│   │   ├── learn/               Lesson and submission components
│   │   ├── profile/             Shared profile forms
│   │   ├── providers/           AuthProvider, SettingsProvider
│   │   ├── sections/            Home page sections
│   │   └── ui/                  Buttons, cards, fields, dialogs, badges
│   ├── data/
│   │   ├── curriculum.ts        Eight-week, 36-day curriculum fixture
│   │   └── faq.ts               FAQ content
│   ├── lib/
│   │   ├── api.ts               All Supabase data access (975 lines)
│   │   ├── config.ts            Environment parsing
│   │   ├── supabase.ts          Client construction
│   │   ├── seo.ts               Per-route metadata
│   │   └── utils.ts             Formatting and helpers
│   ├── pages/
│   │   ├── public pages         Home, Programme, Methodology, Projects, Enrol, FAQ, Contact, legal
│   │   ├── admin/               18 administrator pages
│   │   └── learn/               9 learner pages
│   ├── tests/                   8 Vitest files plus setup
│   └── types/                   Shared TypeScript types
├── supabase/migrations/         19 SQL migrations
├── scripts/                     Weekbook importer, content repair SQL, evaluation script, screenshot tool
├── docs/                        Plans, QA journey book, journey CSV
├── netlify.toml                 Build, SPA fallback and security headers
├── tailwind.config.ts           Design tokens
└── package.json
```

The shape of the repository mirrors the product: public, learner and admin surfaces are separated at the page and component level, and all database access is funnelled through a single API module.

---

## 4. Runtime architecture

### 4.1 Route tree

The route tree is declared in `src/App.tsx`. Public routes are nested under a `PublicLayout`; authenticated learners under `LearnLayout`; administrators under a `RequireAdmin` guard and `AdminLayout`.

```
PublicLayout
├── /                     HomePage
├── /programme            ProgrammePage
├── /methodology          MethodologyPage
├── /projects             ProjectsPage
├── /enrol                EnrolPage
├── /faq                  FAQPage
├── /contact              ContactPage
├── /privacy              PrivacyPage
├── /terms                TermsPage
└── *                     NotFoundPage

Standalone auth
├── /admin/login          AdminLoginPage
├── /login                LoginPage
├── /register             RegisterPage
├── /forgot-password      ForgotPasswordPage
├── /reset-password       ResetPasswordPage
└── /staff                StaffRegisterPage

RequireAdmin → AdminLayout
├── /admin/dashboard
├── /admin/registrations
├── /admin/payments
├── /admin/learners
├── /admin/cohorts
├── /admin/curriculum
├── /admin/curriculum/:weekId
├── /admin/assessments
├── /admin/assessments/:assignmentId
├── /admin/reviews
├── /admin/reviews/:reviewId
├── /admin/publications
├── /admin/remediation
├── /admin/messages
├── /admin/staff
├── /admin/audit-logs
├── /admin/settings
└── /admin/profile

LearnLayout
├── /learn
├── /learn/weeks
├── /learn/weeks/:weekId
├── /learn/lessons/:lessonId
├── /learn/assignments/:assignmentId
├── /learn/submissions/:submissionId/result
├── /learn/remediation
├── /learn/progress
└── /learn/profile
```

### 4.2 Providers

`AuthProvider` owns the Supabase session, the current profile and the role. `SettingsProvider` loads public programme settings (fee, status, dates) once and exposes them to public and enrolment pages. Both wrap the router.

### 4.3 Guard behaviour

`RequireAdmin` is a client-side route guard in `src/App.tsx`. It prevents a learner from seeing the admin shell, but it is explicitly **not** the security boundary. The boundary is the combination of row-level security policies and `is_admin()` checks inside security-definer functions.

Revision 1.14 fixed a real guard bug: `/admin/login` previously redirected any signed-in profile, including learners, to the admin dashboard. It now redirects only administrators and shows a notice when a learner session is present.

### 4.4 Layouts

- `PublicLayout` renders the public header, mobile menu, footer and skip link.
- `LearnLayout` renders the learner shell and requires an authenticated session.
- `AdminLayout` renders the administrator navigation and requires the administrator role.
- Auth pages use a focused frame with no public navigation.

### 4.5 Data access

`src/lib/api.ts` is the single data-access module. It wraps table queries and the following RPCs:

```
get_public_settings          submit_registration        get_registration_status
submit_payment               review_payment             review_free_registration
review_staff_application     submit_contact_message
publish_course_week          unpublish_course_week      set_course_week_lock
```

The file is 975 lines. It contains query functions for cohorts, registrations, payments, lessons, sections, assignments, submissions, assessments, reviews, remediation, messages, staff and settings. Keeping this in one module makes it possible to audit every database call and to ensure no component bypasses the RPC layer for consequential actions.

### 4.6 Error handling

`cleanError()` maps raw Supabase errors to human-readable messages, including duplicate-key and row-level-security failures. UI components surface those messages in toasts or inline states. The application does not swallow errors into silent no-ops.

---

## 5. Data model and migrations

### 5.1 Migration history

| Migration | Purpose |
|---|---|
| `20261114000100_schema.sql` | Core schema: profiles, cohorts, registrations, payment submissions, payment evidence, enrolments, settings, audit logs, contact messages |
| `20261114000200_rpcs.sql` | Registration, payment, review, contact and storage functions |
| `20261114000300_founding_places.sql` | Founding-place terms and reductions |
| `20261114000400_staff.sql` | Staff applications and allowlist |
| `20261115000500_phase2_foundation.sql` | Weeks, lessons, sections, resources, assignments, content revisions |
| `20261115000600_phase2_eight_week_correction.sql` | Eight-week curriculum correction |
| `20261115000700_publish_week_lessons.sql` | Publishing a week also publishes its draft lessons |
| `20261115000800_phase2_learning_spine.sql` | Submissions, versions, files, events, progress, assessments, criteria, evaluation, reviews, publications, remediation, notification outbox |
| `20261115000900_learner_programme.sql` | Learner programme and enrolment-link functions |
| `20261115001000_learner_result_reads.sql` | Learner result access functions |
| `20261115001100_cohort_assignment_sync.sql` | Cohort and assignment synchronisation |
| `20261115001200_weekbook_assignments.sql` | Weekbook assignment seeding |
| `20261116001300`–`01800` | Week 1–6 content repairs |
| `20261116001900_profile_contact_details.sql` | Adds `profiles.phone`, guards identity fields, backfills phones. **Applied and verified 2026-11-16.** |

### 5.2 Core tables

Admissions and identity:

```
profiles                cohorts                 registrations
payment_submissions     payment_evidence        enrollments
site_settings           audit_logs              contact_messages
```

Curriculum:

```
course_weeks            course_lessons          lesson_sections
course_resources        assignments             content_revisions
```

Learning and assessment:

```
submissions             submission_versions     submission_files
submission_events       lesson_progress         assessments
assessment_versions     assessment_criteria     assessment_answer_keys
evaluation_runs         criterion_results       suggested_scores
score_reviews           review_events           score_publications
remediation_cases       remediation_items       remediation_attempts
remediation_events      notification_outbox
```

The schema is broader than a typical course site because it models the teaching process, not just content.

### 5.3 Row-level security

All 39 tables enable row-level security. Policies distinguish:

- anonymous visitors (public settings, public course content, registration and contact submission);
- authenticated learners (their own enrolment, progress, submissions, results and remediation);
- staff applicants (their own application);
- administrators (operational reads and writes, gated by `is_admin()`).

Learner visibility functions (`learner_can_see_lesson`, `learner_can_see_assignment`) encode the rule that a learner sees only published content in an unlocked week for an active enrolment.

### 5.4 Security-definer functions

Consequential operations are functions rather than direct table writes. The function list includes:

- `submit_registration`, `submit_payment`, `review_payment`, `review_free_registration`
- `publish_course_week`, `unpublish_course_week`, `set_course_week_lock`
- `start_submission`, `save_submission_draft`, `submit_assignment`, `submit_review`
- `save_assessment`, `save_assessment_criterion`, `save_review_criterion`
- `publish_score`, `withdraw_publication`
- `start_remediation_item`, `resolve_remediation_item`, `close_remediation_case`
- `get_learner_programme`, `get_learner_result`, `get_learner_submission`
- `is_admin`, `is_enrolled_learner`, `active_enrolment_id`
- `log_content_revision`, `log_table_change`

Each function checks the caller and writes the corresponding event or audit row. The frontend cannot bypass these checks by calling a table directly.

### 5.5 Private receipt storage

Migration 002 creates the `payment-evidence` bucket with:

- `public = false`
- 5 MB file-size limit
- allowed MIME types: JPEG, PNG, PDF
- upload policy gated by `can_upload_evidence(folder)`
- read policy restricted to administrators

The frontend requests a signed URL with a **120-second** expiry (`src/lib/api.ts:570`). Receipts are never exposed through a permanent public URL.

### 5.6 Content revisions and audit logs

`content_revisions` is append-only and records curriculum edits. `audit_logs` records consequential administrative actions. `submission_events`, `review_events` and `remediation_events` preserve the history of learner work. The design principle is that history is data, not a UI affordance.

---

## 6. Authentication and authorisation

### 6.1 Auth flow

Supabase Auth handles email/password sessions. `AuthProvider` subscribes to session changes, loads the matching `profiles` row and exposes `profile.role`.

- `/register` creates an account.
- `/login` signs a learner in.
- `/forgot-password` and `/reset-password` handle recovery.
- `/admin/login` is a separate entry point for administrators.
- `/staff` is a public application form, not an account-creation form.

### 6.2 Role assignment

A profile role is not chosen by the user. Administrator access is granted through the allowlist and review flow. `review_staff_application` promotes an approved applicant. The client-side role check is defence in depth; the database functions check `is_admin()` independently.

### 6.3 Known authorisation gaps

- No interface exists to remove administrator access (DEF-04). Revocation is a SQL procedure.
- The administrator review-to-publication leg is built but has not been exercised live end to end because the QA administrator session was replaced by a learner session during testing.
- The profile migration that adds `phone` (019) is applied and verified, and the admin profile page was exercised live; the learner profile page shares the component but was not exercised with a learner session.

### 6.4 Session handling

`detectSessionInUrl` is disabled because the application uses password auth rather than magic links. Sessions persist and auto-refresh. The unauthenticated `/login` route renders a session-check loading state before deciding whether to show the form or redirect; this is why the documentation screenshot harness could not capture it without an authenticated session.

---

## 7. Enrolment and payment verification

### 7.1 Registration

`submit_registration`:

1. Validates the submitted details.
2. Enforces one registration per email address.
3. Generates a unique reference.
4. Computes the amount due from the active founding-place terms.
5. Writes the registration row and an audit event.
6. Returns the reference and locked price to the client.

The registration is not an enrolment. The confirmation screen states this explicitly.

### 7.2 Payment submission

`submit_payment` accepts transfer details and links the uploaded evidence path. The upload itself goes to the private `payment-evidence` bucket. Complimentary registrations skip payment but still require review through `review_free_registration`.

### 7.3 Verification

`review_payment`:

1. Checks `is_admin()`.
2. Updates the payment submission status.
3. Creates the enrolment when approved.
4. Writes an audit event.
5. Makes the learner area available to the linked account where applicable.

The operation is idempotent enough to prevent duplicate enrolments, and it does not auto-approve. There is no payment gateway and no card data in the system.

### 7.4 Status lookup

`get_registration_status` accepts a reference and email and returns the real state. It is deliberately narrow: it does not expose the full registration record, only the status information the applicant needs.

### 7.5 Defects affecting this flow

- **DEF-01:** the `/enrol` badge always reads "Registration open" even when settings say closed. The banner and button are correct; the badge is not.
- **DEF-02:** cohort dates edited in the admin console do not propagate to the public settings the site reads.

Neither defect can cause an incorrect enrolment, but both can mislead an operator or applicant.

---

## 8. Curriculum content pipeline

### 8.1 Curriculum model

The programme is eight weeks and 36 study days. `src/data/curriculum.ts` defines the canonical week and day sequence, including checkpoints detected from day titles. The public programme page and learner week pages derive from the same model.

### 8.2 Lesson structure

A lesson is a row in `course_lessons`; its content is a set of `lesson_sections`. Sections can be marked `is_private` (for example, answer keys) and are excluded from learner reads by policy and by the learner query functions.

### 8.3 Weekbook import

Teaching content originated in weekbook documents. The repository contains a Python importer (`scripts/import-weekbooks.py`) that:

- extracts sections from the source documents;
- breaks paragraphs by a gap-to-font-size ratio;
- continues prose across page boundaries;
- preserves wrapped table cells on separate lines;
- strips the next day's title and metadata from the final section;
- emits JSON and SQL for review before import.

QA revision 1.15 records the Week 1 pilot: 24 days regenerated, 100 corrected sections imported, three duplicate imports removed and 89 pre-import sections removed (reversibly, through `content_revisions`).

### 8.4 Publishing

`publish_course_week` validates that:

- at least one non-archived lesson exists;
- every lesson has a title;
- every lesson has at least one learner-visible section.

It then sets the week to published and unlocked, stamps the publisher and time, and updates draft lessons to published. This is the fix in migration 007.

`unpublish_course_week` reverses publication. `set_course_week_lock` controls the lock independently of publication.

### 8.5 Content state at documentation time

- Weeks 1–5 published.
- Weeks 6–8 locked.
- Week 1 holds the corrected 100-section pilot.
- 24 assignments seeded.

### 8.6 Content risk

The Day 1 Guided practice steps 4–6 are misnumbered in the source PDF. The import was left verbatim rather than silently corrected, pending a founder decision. This is the correct behaviour for teaching material: a content error should be visible, not quietly rewritten.

---

## 9. Learner experience

### 9.1 Programme and weeks

`get_learner_programme` returns the learner's active enrolment, unlocked weeks and lesson summaries. The learner overview shows where they are and what is available.

### 9.2 Lessons

The lesson page renders sections in order, with private sections omitted. Progress is recorded through `mark_lesson_complete`. The learner can move between lessons within a week.

### 9.3 Assignments and submissions

`start_submission` creates or returns a draft. `save_submission_draft` persists text, links and file references. `submit_assignment` finalises the submission and creates a version and event. Files are stored in a private submission bucket and accessed through policy-controlled reads.

### 9.4 Results

`get_learner_result` returns the published score and feedback only after publication. A learner cannot see an unpublished review. This gate is enforced in the database, not only in the UI.

### 9.5 Remediation

If a learner does not meet the criteria, a remediation case can be opened with specific items. `start_remediation_item`, `resolve_remediation_item` and `close_remediation_case` manage the lifecycle. The learner sees the items and their status.

### 9.6 Profile

`/learn/profile` edits display name and phone. Migration 019 adds the phone column, guards `id`/`email`/`role`, and backfills phones from registrations and staff applications; it was applied and verified on 2026-11-16. The admin profile page was exercised live; the learner page shares the component and is covered by tests but was not exercised with a learner session.

---

## 10. Assessment, review, publication and remediation

### 10.1 Assessment definition

An assessment belongs to an assignment and has versions, criteria and optional answer keys. `save_assessment` and `save_assessment_criterion` write these definitions, with revisions recorded.

### 10.2 Evaluation

`evaluation_runs` and `criterion_results` store an evaluation pass against a submission. `suggested_scores` presents a recommendation to a human reviewer. The system deliberately does not publish an automatic score.

### 10.3 Human review

`start_review` creates a review; `save_review_criterion` records the reviewer's decisions; `submit_review` finalises the review. `score_reviews`, `review_events` and `score_publications` preserve the trail.

### 10.4 Publication

`publish_score` makes the result visible to the learner. `withdraw_publication` reverses it. This separation between review and publication is a core safety property: a score can be corrected before the learner sees it.

### 10.5 Remediation

Remediation is modelled as its own case with items, attempts and events. It is not a free-text note on a submission. That structure makes follow-up measurable.

### 10.6 Test coverage

`src/tests/admin-curriculum.test.tsx` exercises curriculum-admin behaviour. `src/tests/prose.test.tsx` covers the lesson prose renderer. Scoring, publication and remediation are covered primarily by the QA journey book rather than unit tests; this is a gap worth closing with targeted integration tests.

---

## 11. Administrator console

### 11.1 Navigation and layout

`AdminLayout` provides a persistent sidebar grouped by admissions, teaching and operations. Pages are built from shared table, filter, dialog and form components.

### 11.2 Admissions

- **Registrations:** review submitted details, verify or reject.
- **Payments:** inspect receipt metadata, open a signed link, approve or reject.
- **Learners:** view enrolments and progress.
- **Cohorts:** create and edit cohorts.

### 11.3 Teaching

- **Curriculum:** weeks, lessons and sections.
- **Week editor:** create, reorder and publish lessons; preview with keys hidden; withdraw, lock and unlock.
- **Assessments:** define criteria and answer keys.
- **Reviews:** open a submission, score against criteria, submit.
- **Publications:** release or withdraw scores.
- **Remediation:** open cases, add items, follow up.

### 11.4 Operations

- **Messages:** contact form submissions.
- **Staff:** review applications and promote approved staff.
- **Audit logs:** inspect recorded actions.
- **Settings:** programme fee, status and public settings.
- **Profile:** administrator display name and phone.

### 11.5 Operational gaps

- No delete or archive for cohorts and registrations (DEF-05).
- No administrator revocation UI (DEF-04).
- Cohort dates do not propagate publicly (DEF-02).
- The dashboard prioritises counts; ageing and queue-time views are not implemented.

---

## 12. Design system implementation

### 12.1 Tokens

Design tokens live in `tailwind.config.ts`:

- colour scales: `ink`, `line`, `mist`, `muted`, `violet`, `ivory`, `navy`, `amber`, `sage`, status colours;
- font families: `display` (Fraunces), `sans` (Manjari/Inter), `mono` (JetBrains Mono);
- container width: `1520px`;
- radii: `2rem`, `2.75rem`;
- shadows: `glow`, `glow-sm`, `panel`, `ivory`;
- motion: `fade-up`, `float`, `pulse-glow`, `shimmer`;
- easing: `editorial`.

### 12.2 Components

`src/components/ui` provides the shared primitives: buttons, cards, badges, fields, dialogs and section headings. `src/components/layout` provides the public header, footer and mobile navigation. Section components in `src/components/sections` compose the home page.

### 12.3 Accessibility implementation

- A skip link targets `#main`.
- Landmarks are semantic (`header`, `nav`, `main`, `footer`).
- The mobile menu traps focus, closes on Escape and restores focus to the trigger.
- Forms use explicit labels and browser validation.
- Status is conveyed by text and shape, not colour alone.
- `prefers-reduced-motion` disables non-essential animation and smooth scrolling.

### 12.4 Asset strategy

The public site uses SVG illustrations and CSS-composed interface motifs rather than stock photography. Icons come from `lucide-react`. The captured pages contained no raster images, which keeps the initial payload small and the visual language consistent.

### 12.5 Trade-offs

The visual system is richer than a default Tailwind admin theme: custom colour scales, display typography, grain and glow. That costs some CSS weight and requires discipline in component reuse. The benefit is that public and internal surfaces feel like one product.

---

## 13. Quality assurance and testing

### 13.1 Unit and component tests

Ten Vitest files cover:

| File | Area |
|---|---|
| `content.test.ts` | Content helpers and formatting |
| `curriculum.test.ts` | Week/day model and checkpoints |
| `progress.test.ts` | Progress calculations |
| `utils.test.ts` | Shared utilities |
| `validation.test.ts` | Form and input validation |
| `prose.test.tsx` | Lesson prose rendering |
| `profile.test.tsx` | Profile editing |
| `admin-curriculum.test.tsx` | Curriculum administration |
| `admin-nav.test.tsx` | Administrator navigation |
| `data-table.test.tsx` | Shared table behaviour |

A run of `npx vitest run` on 16 November 2026 returned **94 tests in 10 files, all passing**. An earlier run in the same pass failed one assertion because `admin-curriculum.test.tsx` queried `role="article"` after the page moved to the shared `DataTable`, which renders a semantic `<table>` and `<tr>` rows. The test now queries the table rows; the interface was not changed. The QA book records the result as revision 1.20.

The QA book's earlier **85** and the README's earlier **26** described different snapshots. Both documents have been reconciled to the current 94-test suite.

### 13.2 Hand-executed journey book

`docs/QA-USER-JOURNEYS.md` v1.20 defines 170 checks:

| Group | Count | Coverage |
|---|---|---|
| Global | 16 | Shell, navigation, accessibility |
| Learner/public | 79 | Public pages, registration, payment, learning |
| Staff applicant | 6 | Application and review |
| Administrator | 69 | Curriculum, assessment, review, publication, operations |

The book requires both UI and database state to be correct for a pass. It is the most valuable quality artefact in the project because it tests the operation, not just the render.

### 13.3 Type checking and lint

`npm run typecheck` runs `tsc -b` with strict settings. The 2026-11-16 re-run confirmed a clean typecheck, `npm run lint` returning 32 warnings and 0 errors, the full 94-test suite passing, and a passing production build (`tsc -b && vite build`). The lint warnings are known and not treated as release blockers.

### 13.4 Browser evidence

Fifteen screenshots were captured from the local app for this documentation set. The harness verified page readiness, fonts, images, finite animations, zero runtime errors and no horizontal overflow at 1440 × 1000 and 390 × 844. Interaction checks covered the FAQ accordion and the mobile navigation.

### 13.5 Testing gaps

- No authenticated learner or administrator E2E suite runs in CI.
- No payment-flow integration test with a real storage upload.
- No accessibility audit using axe or a screen reader was recorded.
- No performance budget or load test exists.
- The QA book is manual; its CSV tracker records runs but does not execute them.

---

## 14. Build, deployment and operations

### 14.1 Build

`npm run build` runs `tsc -b` then `vite build`, producing a static bundle in `dist/`. There is no server-side runtime; all dynamic behaviour comes from Supabase.

### 14.2 Hosting configuration

`netlify.toml` specifies:

- build command `npm run build`;
- publish directory `dist`;
- Node 24;
- SPA fallback from `/*` to `/index.html` with status 200;
- security headers: `X-Content-Type-Options`, `X-Frame-Options: DENY`, strict referrer policy, permissions policy, and a content security policy allowing only self plus Supabase connections;
- immutable caching for `/assets/*`.

### 14.3 Release state

| Release | State | Notes |
|---|---|---|
| Revisions 1.1–1.5 | Live | Commit `abd9d36`, bundle `assets/index-Ya_h9iRI.js` |
| Revisions 1.6–1.19 | Working tree only | Application changes; not committed, not deployed |
| Revision 1.20 | Working tree only | Test and documentation alignment; no runtime change |
| Migration 019 | Applied and verified 2026-11-16 | Profile phone column and identity guards |
| Weeks 1–5 | Published | Weeks 6–8 locked |

The QA book's rule is that a revision is not finished until the deployed bundle is confirmed to contain it. That rule is why the release state is stated so precisely here.

### 14.4 Operational procedures

- Payment verification is manual and happens in `/admin/payments`.
- Receipt access uses 120-second signed links.
- Content edits are recorded in `content_revisions`.
- Administrative actions are recorded in `audit_logs`.
- QA test data must be cleaned up by SQL because there is no delete UI (DEF-05).

### 14.5 Security posture

- No service-role key in the browser.
- No public admin creation.
- No automatic payment confirmation.
- No card or banking credential storage.
- Receipts private.
- RLS on all tables.
- Security-definer functions check roles.
- CSP restricts script and connection origins.

This is a deliberately conservative posture for a small academy handling money and learner records.

---

## 15. Status, gaps and next engineering steps

### 15.1 What is complete

- Public site with nine routes and composed home sections.
- Registration, status lookup, receipt upload and manual verification.
- Learner area with weeks, lessons, progress, assignments, results, remediation and profile.
- Administrator console across admissions, teaching and operations.
- 39-table schema with RLS, audit trails and private storage.
- 170-check QA journey book and a 94-test automated suite, all passing.
- Netlify build and security configuration.

### 15.2 What is not complete

| Item | State | Impact |
|---|---|---|
| Slack notifications | Not implemented | The notification outbox exists; delivery does not |
| Migration 019 | Applied and verified | Profile phone is supported; the learner profile page remains unexercised with a learner session |
| Revisions 1.6–1.19 | Uncommitted | The live site lacks the Phase 2 platform |
| Live admin review-to-publication pass | Not run | The leg is built but unverified end to end |
| DEF-01 | Open | Enrolment badge can contradict closed status |
| DEF-02 | Open | Cohort dates do not reach the public site |
| DEF-04 | Open by design | Admin revocation requires SQL |
| DEF-05 | Accepted | No delete/archive UI |

### 15.3 Documentation discrepancies

Resolved in the 16 November 2026 QC pass:

1. **DEF-07 is now marked resolved in the QA book.** Migration `20261115000700_publish_week_lessons.sql` publishes a week's draft lessons in the same transaction; the stale defect row has been replaced.
2. **Migration 019 status is consistent.** The QA header, revision 1.16 and the deployed-state note all record that `20261116001900_profile_contact_details.sql` was applied and verified on 2026-11-16.
3. **Test counts are reconciled.** The README, the QA book (revision 1.20) and this build log all describe the current 94-test suite.
4. **The README now reflects the implemented routes, migrations and deployment host.** The learner area is explicitly described as working-tree only.

Still open:

5. **No research or usability archive exists.** Engineering decisions are documented; participant evidence is not.

### 15.4 Recommended next steps

1. Commit and deploy revisions 1.6–1.19 after a regression pass; revision 1.20 is test and documentation only.
2. Exercise the administrator review-to-publication leg with a real administrator session.
3. Exercise the learner profile page with a learner session.
4. Complete Slack delivery or remove the outbox from the release scope.
5. Fix DEF-01 and DEF-02 before the next enrolment window.
6. Add authenticated end-to-end tests for the learner and admin journeys.

### 15.5 Maintenance notes

- Keep all consequential writes inside security-definer functions.
- Never expose the service-role key to the client.
- Keep receipts in the private bucket and use short-lived links.
- Add a QA revision row for every change that affects a journey.
- Confirm the deployed bundle after every release; a local build is not a deployment.

---

### Evidence index

| Evidence | Location |
|---|---|
| Route tree | `src/App.tsx` |
| Data access | `src/lib/api.ts` |
| Supabase client | `src/lib/supabase.ts` |
| Design tokens | `tailwind.config.ts` |
| Curriculum model | `src/data/curriculum.ts` |
| Schema and functions | `supabase/migrations/` |
| Importer | `scripts/import-weekbooks.py` |
| QA journey book | `docs/QA-USER-JOURNEYS.md` |
| Deployment config | `netlify.toml` |
| Product rationale | [PROJECT_CASEBOOK.md](./PROJECT_CASEBOOK.md) |
