# CraftCode Academy — Project Casebook

**Document type:** Product design casebook  
**Project:** CraftCode Academy  
**Owner:** HelsaGrace Okporho  
**Documented:** 16 November 2026  
**Primary evidence:** running application at `http://127.0.0.1:5175`, source repository, `docs/QA-USER-JOURNEYS.md` (v1.20), captured screenshots  
**Companion document:** [PROJECT_BUILD_LOG.md](./PROJECT_BUILD_LOG.md)

> This casebook describes what exists and why it exists. It separates the live public release from the uncommitted working tree, and it distinguishes design intent from verified behaviour. Where the evidence is incomplete, the gap is stated rather than filled.

---

## 1. Project identity

| Field | Detail |
|---|---|
| **Name** | CraftCode Academy |
| **Type** | Frontend development academy and learner platform |
| **Category** | Education technology · vocational training · cohort-based learning |
| **Geography** | Nigeria; fees quoted in Nigerian Naira; manual Nigerian bank transfer |
| **Owner and designer** | HelsaGrace Okporho |
| **Programme** | Eight weeks, 36 structured study days, one capstone project |
| **Fee** | ₦20,000, with founding places that can reduce or waive the fee |
| **Public release** | `https://craftcode-academy.netlify.app` (revisions 1.1–1.5, commit `abd9d36`) |
| **Current state** | Phase 2 complete in the working tree; revisions 1.6–1.19 are not committed or deployed (1.20 is test/documentation only) |
| **Repository** | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode` |

CraftCode Academy is not a course landing page with a payment button attached. It is an operating academy: a public programme site, a reviewed enrolment pipeline, a cohort record, a learner area with lessons and assignments, an assessment and review workflow, and an administrator console. The design problem therefore spans marketing, admissions operations and day-to-day teaching.

---

## 2. Executive overview

CraftCode Academy teaches complete beginners to build for the web over eight weeks. The public site explains the programme honestly, the enrolment flow registers a person before payment, and the academy verifies a real bank transfer before granting learner access. The learner area delivers 36 study days across eight weeks, assignments, feedback and remediation. The administrator area manages registrations, payment evidence, cohorts, curriculum, assessments, reviews, publications, messages, staff applications and audit logs.

The central design decision is that **enrolment is a reviewed process, not a checkout**. There is no payment gateway, no card collection and no automatic confirmation. A registration produces a reference and a locked price; the applicant transfers money through their own bank; the academy checks the transfer and then enrols the learner. That decision shapes the information architecture, the language, the status states and the security model.

The interface is deliberately editorial rather than corporate: a dark violet identity, a serif display face, a mono label system, and long-form sections that explain the programme before asking for money. The design tries to answer the questions a sceptical beginner actually asks — what will I learn, who is teaching me, what does it cost, what happens if I pay, and what is this programme *not* promising.

**Status in one line:** The public site is live at revisions 1.1–1.5; the full Phase 2 platform is built and tested in the working tree, with a documented list of small operational gaps. Migrations 001–012 and 019 are recorded as applied and verified; the Week 1 content repair is recorded as imported in QA revision 1.15; the 014–018 repair files remain in the working tree. The Phase 2 application code is not deployed.

---

## 3. Context

### 3.1 The market context

A beginner in Nigeria who wants to learn frontend development faces a crowded and uneven market: free video libraries with no structure, bootcamps priced in foreign currency, and social-media courses that promise employment without evidence. The cost of entry is not only money. It is the risk of spending months on unstructured content and finishing without a single presentable project.

CraftCode Academy was designed for that gap: a fixed sequence, a defined daily workload, one substantial capstone, and a price expressed in the currency the learner actually earns.

### 3.2 The operational context

The academy is run by a small team. That constraint is visible in the product. Payment verification is manual because the operator must confirm a real bank transaction. Administrator access is allowlisted because there is no large support organisation to monitor account creation. Curriculum authoring is deliberate and reviewable because the founder is accountable for what is taught.

These are not compromises hidden behind a polished interface. They are stated in the product and enforced in the database.

### 3.3 The project context at documentation time

The repository contains more than the deployed site. The QA book records revisions 1.1–1.5 as live, and revisions 1.6–1.19 as working-tree changes that have not been committed or deployed. This casebook documents the whole working tree, but it labels the deployed surface separately wherever that distinction matters.

---

## 4. The problem

### 4.1 The learner's problem

A beginner does not know what to learn first, how much to learn each day, or when they are ready to build something real. Most available material assumes more context than they have, or teaches tools before fundamentals. The learner needs a sequence they can trust, a daily scope they can finish, and a final project that proves the sequence worked.

### 4.2 The academy's problem

The academy must convert interest into a verified cohort without pretending to be a payment processor. It must:

- collect accurate registration details before money moves;
- give the applicant a stable reference and a locked price;
- accept private proof of a bank transfer;
- let an administrator verify the transfer and enrol the learner;
- deliver a structured curriculum with lessons, assignments and feedback;
- keep learner work and payment evidence private;
- preserve an audit trail for consequential actions.

### 4.3 The trust problem

A new academy has no reputation to borrow. The interface has to earn trust through specificity: exact weeks, exact days, exact inclusions, a named capstone, a clear fee, a stated refund position, and an explicit list of what the programme does **not** guarantee. Vague ambition would make the offer less credible, not more.

### 4.4 What I deliberately did not solve

I did not design an automated payment gateway, a public student marketplace, a job-placement guarantee, or a multi-academy tenancy model. Those are different products with different regulatory and operational burdens. The scope is one academy, one programme, one cohort model, designed to be run honestly by a small team.

---

## 5. Goals and non-goals

### 5.1 Goals

| Goal | How the product expresses it |
|---|---|
| Make the programme legible before purchase | A dedicated programme page with eight weeks and 36 days, plus a methodology page |
| Reduce ambiguity at the point of payment | A four-step enrolment explanation, a locked price, and a unique reference |
| Keep money handling honest | Manual bank transfer, private receipt upload, administrator verification |
| Give beginners a real daily scope | 36 study days grouped into eight weeks, with checkpoints and a capstone |
| Support teaching, not just content delivery | Lessons, assignments, submissions, assessment criteria, reviews and remediation |
| Protect learner and applicant data | Row-level security, private buckets, short-lived signed links, allowlisted admins |
| Make the operation auditable | Append-only revisions, audit logs, submission events and review events |

### 5.2 Non-goals

- A public course catalogue with self-serve checkout.
- Card payments or stored banking credentials.
- Automatic enrolment on payment submission.
- A promise of employment or a salary outcome.
- A social network, forum or public learner profile.
- Multi-tenant academy administration.
- Fully automated grading without human review.

The non-goals matter as much as the goals. They keep the product small enough to operate credibly.

---

## 6. Users and roles

### 6.1 Prospective learner

A beginner evaluating the programme. They need to understand the curriculum, the time commitment, the fee and the enrolment process. Their critical moment is deciding whether to transfer ₦20,000 to an academy they have not used before.

### 6.2 Applicant

A person who has registered but is not yet enrolled. They hold a reference, may owe a reduced or waived fee, and may have uploaded a receipt. Their critical moment is uncertainty: *did my payment arrive, and am I in?* The status lookup exists for that moment.

### 6.3 Enrolled learner

A verified learner with access to `/learn`. They work through weeks, read lessons, submit assignments, read results, and complete remediation where required. Their critical moments are knowing what to do today and understanding why an assignment was scored as it was.

### 6.4 Staff applicant

A person applying to teach or support the academy. They are not yet an administrator. Their application is reviewed through an allowlist and promotion flow.

### 6.5 Administrator

The operator of the academy. They review registrations, verify payments, manage cohorts, author curriculum, define assessments, review submissions, publish scores, handle remediation, read messages, manage staff and inspect audit logs. Their critical moment is any action that changes a learner's access or record.

### 6.6 Role model in the product

| Role | Entry point | Gate |
|---|---|---|
| Visitor | Public routes | None |
| Applicant | `/enrol`, status lookup | Registration reference and email |
| Learner | `/login` → `/learn/*` | Authenticated session linked to an enrolment |
| Staff applicant | `/staff` | Public application form |
| Administrator | `/admin/login` → `/admin/*` | Authenticated session plus administrator role |

The client-side role check is defence in depth. The database policies and security-definer functions are the actual gate.

---

## 7. Product strategy

### 7.1 Sell the sequence, not the dream

The programme page does not lead with income claims. It leads with the order of instruction: the web and HTML, then CSS, then JavaScript, then the DOM, then asynchronous work, then React, then TypeScript, then a capstone. The promise is comprehension and a finished project, not a job.

### 7.2 Separate interest from commitment

Registration and enrolment are different states. A person can register, receive a reference and a price, and then decide whether to pay. The academy can review the registration before money arrives. This reduces both accidental payments and mismatched expectations.

### 7.3 Design the waiting state

Manual verification creates a period between payment and access. Instead of hiding that period, the product gives the applicant a status lookup and a confirmation screen that explains what happens next. A process with a wait is easier to trust when the wait is visible.

### 7.4 Teach with the same rigour as the marketing

The learner area is not an afterthought. Lessons are structured into sections; assignments have criteria; submissions have versions and events; reviews produce suggested scores, human decisions and publications; remediation has its own case and item model. The academy's credibility depends on the teaching layer, not the landing page.

### 7.5 Keep the operator's workload honest

Every manual step is visible in the admin console: registrations to review, payments to verify, submissions to assess, reviews to publish, remediation to follow up. The interface is designed around queues rather than abstract dashboards.

---

## 8. Feature set

The table below records the feature set found in the working tree. It is not a wish list.

| Area | Feature | Status |
|---|---|---|
| Public site | Home, programme, methodology, projects, FAQ, contact, privacy, terms | Implemented |
| Public site | Programme snapshot, teaching promises, pricing, honest expectations, FAQ preview, final CTA | Implemented |
| Enrolment | Registration form with unique reference and locked price | Implemented |
| Enrolment | Founding places (free to 10% off) | Implemented |
| Enrolment | Status lookup by reference and email | Implemented |
| Enrolment | Private receipt upload | Implemented |
| Enrolment | Manual administrator verification and enrolment | Implemented |
| Accounts | Sign in, registration, forgot password, reset password | Implemented |
| Staff | Public staff application and admin review | Implemented |
| Learner | Programme overview, weeks, lessons, progress | Implemented |
| Learner | Assignment workspace and submission | Implemented |
| Learner | Result and feedback view | Implemented |
| Learner | Remediation | Implemented |
| Learner | Profile (display name, phone) | Implemented; migration 019 applied and verified |
| Admin | Dashboard, registrations, payments, learners, cohorts | Implemented |
| Admin | Curriculum and week editor | Implemented |
| Admin | Assessments and assessment editor | Implemented |
| Admin | Reviews and review detail | Implemented |
| Admin | Publications, remediation, messages | Implemented |
| Admin | Staff, audit logs, settings, profile | Implemented |
| Platform | Row-level security across learner and admin data | Implemented |
| Platform | Private receipt storage with signed links | Implemented |
| Platform | Content revisions and audit logging | Implemented |
| Platform | Notification outbox | Implemented in schema; Slack delivery is the one Phase 2 item not complete |
| Platform | Automated email/Slack notifications | Partially implemented; see the build log |
| Platform | Payment gateway | Not built, by design |
| Platform | Automated grading without human review | Not built, by design |

---

## 9. Information architecture

### 9.1 Public architecture

```
/                     Home — the offer and the argument
/programme            The eight weeks and 36 days in detail
/methodology          How teaching works, day by day
/projects             The OpenShelf capstone and what it proves
/enrol                Registration, fee, payment steps, status lookup
/faq                  Straight answers before enrolling
/contact              Questions and support
/privacy              Data handling
/terms                Programme terms
```

The public navigation is deliberately shallow. A visitor can reach the programme, the teaching method, the project and the price in one click from the header. The footer repeats the same paths for orientation.

### 9.2 Account architecture

```
/login                Learner sign-in
/register             Account creation
/forgot-password      Password recovery request
/reset-password       Password reset
/staff                Staff application
/admin/login          Administrator sign-in
```

### 9.3 Learner architecture

```
/learn                         Programme overview
/learn/weeks                   All weeks
/learn/weeks/:weekId           A week and its lessons
/learn/lessons/:lessonId       A lesson
/learn/assignments/:id         Assignment workspace
/learn/submissions/:id/result  Result and feedback
/learn/remediation             Remediation
/learn/progress                Progress
/learn/profile                 Profile
```

### 9.4 Administrator architecture

```
/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
```

The admin navigation is grouped by operational responsibility rather than by database table. Registration and payment review sit together because they are one admission decision. Curriculum, assessments and reviews sit together because they are one teaching cycle.

---

## 10. Key user flows

### 10.1 Evaluate the programme

1. Visitor lands on `/` and reads the promise, the eight-week snapshot and the price.
2. They open `/programme` to see week-by-week content and the 36-day structure.
3. They open `/methodology` to understand how a study day runs.
4. They open `/projects` to see the capstone they will build.
5. They open `/faq` for objections and `/enrol` when ready.

Design intent: no dead ends. Every public page offers a route to the programme or to enrolment without forcing a modal or a form.

### 10.2 Register and pay

1. Applicant completes the registration form on `/enrol`.
2. The system returns a unique reference and the amount due, including any founding-place reduction.
3. The confirmation explains the bank transfer step and the receipt upload.
4. The applicant transfers the money through their own bank.
5. The applicant uploads transfer details and a receipt.
6. The academy verifies the transaction.
7. The applicant becomes an enrolled learner and can sign in.

The critical UX property is that the applicant always knows which step they are in and what the academy will do next.

### 10.3 Check status

An applicant who is unsure uses the status lookup with their reference and email. The result reflects the real database state: registered, payment submitted, verified or enrolled. This is the antidote to the anxiety created by a manual process.

### 10.4 Learn a day

1. Learner signs in and lands on the programme overview.
2. They open the current week and then the current lesson.
3. The lesson presents concept sections, examples and a guided practice sequence.
4. Private sections (such as answer keys) are excluded from the learner view.
5. The learner marks progress and moves to the assignment.

### 10.5 Submit and receive feedback

1. Learner opens the assignment workspace.
2. They submit text, links or files as the assignment requires.
3. The submission is versioned; each action is recorded as an event.
4. An administrator reviews the submission against criteria.
5. A suggested score and a human decision are recorded.
6. The score is published.
7. The learner sees the result and feedback, or a remediation path if required.

### 10.6 Operate the academy

An administrator works through queues: new registrations, submitted payments, submissions awaiting review, scores awaiting publication, remediation follow-ups, and staff applications. Consequential actions are written to audit logs.

---

## 11. UX and interface decisions

### 11.1 Explain before asking

The home page spends most of its length explaining the programme before the final call to action. The price section states what is included and, in the same panel, states that completing the programme is not a job guarantee. This is a deliberate trade: a shorter page might convert more impulsive clicks, but it would attract the wrong applicants and create support load.

### 11.2 Name the process

The enrolment page labels the four steps — register, pay, submit receipt, get verified — and states that registration is not confirmed enrolment. The wording is operational, not promotional. The goal is that nobody transfers money believing they have already bought access.

### 11.3 Make the fee concrete

The fee is displayed as a number in Naira, not as a monthly abstraction. Founding places are explained as a real reduction, not a countdown device. The page states that cards are not collected on the site. These choices reduce the fear of an invisible charge.

### 11.4 Treat waiting as a designed state

Manual verification means the applicant waits. The confirmation screen and the status lookup make that wait legible. The product does not simulate instant success, because doing so would be a lie about the operation.

### 11.5 Keep the honest list visible

The "what this programme is — and what it is not" section exists because trust is built by boundaries. It states that the programme is beginner-level, structured and project-based, and that it is not a shortcut to employment. This is the kind of copy that protects both the learner and the academy.

### 11.6 Design the admin as a set of queues

The administrator does not need a chart of total registrations. They need to know what requires action now. The navigation and page structure prioritise pending work: registrations to review, payments to verify, reviews to complete, publications to release.

### 11.7 Preserve the learner's context

Lessons keep the week and lesson structure visible. Assignments keep the criteria and the submission state visible. Results show the feedback rather than only a number. The learner should never have to guess where they are in the programme.

### 11.8 Accessibility as a baseline, not a feature

The public pages use semantic landmarks, a skip link, labelled controls, visible focus states and reduced-motion handling. Forms use labels and browser validation. The mobile menu traps focus, closes on Escape and restores focus to the trigger. These are baseline expectations for an academy that teaches accessibility.

---

## 12. Visual direction and design system

### 12.1 Direction

The visual identity is editorial and technical at the same time: a dark ink background for the public argument, ivory panels for dense information, and violet as the single accent. The serif display face gives the programme a considered, academic tone; the mono face marks labels, steps and metadata; the humanist sans carries body copy.

The result is neither a generic SaaS gradient nor a traditional school website. It reads as a studio-built academy: confident, specific and slightly austere.

### 12.2 Palette

| Token | Value | Role |
|---|---|---|
| `ink.950` | `#08080D` | Deepest background |
| `ink.900` | `#0A0A0F` | Primary dark surface |
| `ink.850` | `#0F0F16` | Raised dark surface |
| `ink.800` | `#13131A` | Panels |
| `ink.700` | `#1C1C26` | Borders and controls |
| `line` | `#2A2A3A` | Dividers |
| `mist` | `#F0F0F5` | Primary light text on dark |
| `muted` | `#9898A8` | Secondary text |
| `violet` | `#7C3AED` | Primary accent |
| `violet.light` | `#A78BFA` | Accent on dark |
| `ivory` | `#EFECF6` | Light section background |
| `ivory.card` | `#F7F6FB` | Light card surface |
| `navy` | `#1A1529` | Text on ivory |
| `amber` | `#E9A45D` | Warning and attention |
| `sage` | `#B9D78A` | Positive and open status |
| `success` | `#10B981` | Success |
| `warning` | `#F59E0B` | Warning |
| `danger` | `#EF6A6A` | Error and destructive |

Defined in `tailwind.config.ts` (Tailwind 3.4).

### 12.3 Typography

| Role | Family | Usage |
|---|---|---|
| Display | Fraunces Variable | Headlines, programme titles, large figures |
| Body | Manjari (with Inter fallback) | Paragraphs and interface copy |
| Mono | JetBrains Mono Variable | Labels, steps, metadata, status |

The type scale is fluid, using `clamp()` for display sizes. Display headings use tight tracking and a low line height; body copy is generous, around 1.7–1.8 line height. Labels are uppercase mono with wide tracking.

### 12.4 Layout and components

- Maximum content width: `1520px`.
- Large radii: `2rem` and `2.75rem` for major panels.
- Glow shadows keyed to violet for primary actions.
- Ivory bands for long-form information; dark bands for the argument.
- Grain texture on light bands to avoid a flat digital surface.
- Section headings use an eyebrow, a display title and a description.
- Status is expressed with small caps, dots and toned badges rather than colour alone.

### 12.5 Motion

Motion is restrained: fade-up on entry, a slow float on decorative elements, and a soft glow pulse. The interface respects `prefers-reduced-motion`. The enrolment confirmation scroll is instant when reduced motion is requested.

### 12.6 What the system avoids

- Stock photography of classrooms.
- Testimonial carousels with unverifiable claims.
- Countdown timers and scarcity theatrics.
- A dashboard aesthetic on public pages.
- Purple used decoratively without a functional role.

---

## 13. Screen inventory

All screenshots were captured on 16 November 2026 from the local application at `http://127.0.0.1:5175` using isolated headless Chrome with no authenticated session. Desktop viewport: 1440 × 1000. Mobile viewport: 390 × 844. Every captured page reported zero horizontal overflow and zero runtime errors. The capture manifest is at [`PROJECT_ASSETS/supporting-evidence/capture-manifest.json`](./PROJECT_ASSETS/supporting-evidence/capture-manifest.json).

### 13.1 Desktop

| Screen | Image | What it shows |
|---|---|---|
| Home | [`screenshots/home-desktop.png`](./PROJECT_ASSETS/screenshots/home-desktop.png) | Dark hero with the programme promise, the code-editor motif, the eight-week snapshot, the capstone and the fee |
| Programme | [`screenshots/programme-desktop.png`](./PROJECT_ASSETS/screenshots/programme-desktop.png) | The eight weeks and 36 days, with expandable week detail and daily structure |
| Methodology | [`screenshots/methodology-desktop.png`](./PROJECT_ASSETS/screenshots/methodology-desktop.png) | The three teaching promises and the nine-part study day |
| Projects | [`screenshots/projects-desktop.png`](./PROJECT_ASSETS/screenshots/projects-desktop.png) | The OpenShelf capstone, what it does and how the weeks contribute |
| Enrolment | [`screenshots/enrolment-desktop.png`](./PROJECT_ASSETS/screenshots/enrolment-desktop.png) | Registration form, fee panel, four-step process and status lookup |
| FAQ | [`screenshots/faq-desktop.png`](./PROJECT_ASSETS/screenshots/faq-desktop.png) | Accordion answers with the first item open |
| Contact | [`screenshots/contact-desktop.png`](./PROJECT_ASSETS/screenshots/contact-desktop.png) | Contact routes and support expectations |

### 13.2 Mobile

| Screen | Image | What it shows |
|---|---|---|
| Home | [`mobile/home-mobile.png`](./PROJECT_ASSETS/mobile/home-mobile.png) | The same argument stacked for a 390px viewport |
| Programme | [`mobile/programme-mobile.png`](./PROJECT_ASSETS/mobile/programme-mobile.png) | Week accordions and day detail on mobile |
| Methodology | [`mobile/methodology-mobile.png`](./PROJECT_ASSETS/mobile/methodology-mobile.png) | Teaching promises and study-day sequence |
| Projects | [`mobile/projects-mobile.png`](./PROJECT_ASSETS/mobile/projects-mobile.png) | Capstone description and contribution table |
| Enrolment | [`mobile/enrolment-mobile.png`](./PROJECT_ASSETS/mobile/enrolment-mobile.png) | Registration form and fee summary in a single column |
| FAQ | [`mobile/faq-mobile.png`](./PROJECT_ASSETS/mobile/faq-mobile.png) | Accordion behaviour at mobile width |
| Contact | [`mobile/contact-mobile.png`](./PROJECT_ASSETS/mobile/contact-mobile.png) | Support routes at mobile width |
| Navigation open | [`mobile/navigation-open-mobile.png`](./PROJECT_ASSETS/mobile/navigation-open-mobile.png) | The mobile menu in its open state |

### 13.3 Screens not captured, and why

| Screen | Reason |
|---|---|
| `/login` | The unauthenticated session renders a session-check loading state with no `main` element, so the capture harness could not verify a stable page. Capturing it would have produced a misleading image. |
| `/learn/*` | Requires an enrolled learner session. No credentials were used. |
| `/admin/*` | Requires an administrator session. No credentials were used. |
| Status lookup result | Requires a real registration reference. Creating test data would have written to the database. |

The learner and administrator areas are documented from source, QA records and database migrations, not from screenshots. That limitation is stated again in section 19.

---

## 14. Technical architecture, from a design perspective

The product is a React single-page application backed by Supabase. The design implications of that architecture are significant:

- **Route-level separation of audiences.** Public, learner and administrator areas are separate route trees with separate layouts. A visitor never sees a flash of the admin shell.
- **Database-enforced access.** The interface hides actions a role cannot perform, but the database policies are the gate. This is why the design can show a disabled control without pretending it is a security boundary.
- **Private media.** Receipts are stored privately and served through short-lived signed links. The design never assumes a permanent public URL.
- **Server functions for consequential actions.** Enrolment, verification, publishing, scoring and remediation run through database functions that check the caller's role and write audit events.
- **Content as data.** Weeks, lessons, sections, assignments and assessments are rows, not hard-coded pages. The curriculum can be authored and revised without a deploy.
- **Append-only history.** Content revisions, submission events, review events and audit logs preserve what happened. The interface can show history because the data model keeps it.

A full engineering account is in the [build log](./PROJECT_BUILD_LOG.md).

---

## 15. Key decisions and trade-offs

### 15.1 Manual bank transfer instead of a payment gateway

**Decision:** Accept payment by Nigerian bank transfer and verify it manually.

**Why:** It matches how the audience actually pays, avoids card processing fees and regulatory overhead, and lets the academy confirm the money is real before granting access.

**Trade-off:** The applicant waits, and the operator carries a verification workload. The product mitigates this with a status lookup and a clear four-step explanation, but it does not remove the wait.

### 15.2 Register first, pay second

**Decision:** Registration creates a record and a locked price before any money moves.

**Why:** It separates intent from commitment, gives support a reference to work with, and prevents payments from people who have not read the terms.

**Trade-off:** More steps before revenue. The design compensates by making the process short and the next action explicit.

### 15.3 Allowlisted administrators instead of open staff accounts

**Decision:** Administrator access is granted through an allowlist and a review flow.

**Why:** A small academy cannot monitor open registration for privileged accounts. The allowlist keeps the attack surface small.

**Trade-off:** Removing access still requires a database procedure; there is no "remove administrator" interface. This is recorded as DEF-04.

### 15.4 Private receipts instead of a public upload bucket

**Decision:** Payment evidence lives in a private bucket and is accessed through short-lived signed links.

**Why:** A receipt can contain a name, a bank reference and a partial account number. A public URL would be a data leak.

**Trade-off:** Every review requires a signed-link request. The admin experience is slightly slower, and that is acceptable.

### 15.5 One programme instead of a catalogue

**Decision:** The public site describes one eight-week programme, not a catalogue of courses.

**Why:** A single programme can be explained properly. A catalogue would require comparison logic, pricing variants and content the academy does not yet have.

**Trade-off:** Less surface for search traffic and no upsell path. The depth is the strategy.

### 15.6 Honest limits on the marketing page

**Decision:** State what the programme is not, including that it is not a job guarantee.

**Why:** It filters unrealistic applicants and protects the academy's credibility.

**Trade-off:** Some conversion is lost. The applicants who remain are better prepared.

### 15.7 A real curriculum model instead of rich-text pages

**Decision:** Model weeks, lessons, sections, assignments, criteria, submissions, reviews and remediation as structured data.

**Why:** Teaching requires state: who submitted, what was scored, what was published, what needs remediation. Rich text cannot carry that.

**Trade-off:** More schema and more admin surface. The build log records the cost.

### 15.8 Keep the working tree honest

**Decision:** Do not present revisions 1.6–1.19 as deployed.

**Why:** The QA book distinguishes the live release from the working tree. Documentation that blurred that line would misrepresent the product.

**Trade-off:** The public site currently shows less than the product can do. The next release closes that gap.

---

## 16. Challenges and constraints

### 16.1 Small-team operations

Every manual review is a real task for a real person. The design cannot pretend otherwise. The admin console is therefore organised around queues and clear next actions, not around analytics.

### 16.2 Trust without a track record

The academy cannot rely on logos, alumni numbers or press coverage it does not have. It relies on specificity: the exact curriculum, the exact fee, the exact process, the exact limits. This is slower to write and more honest to read.

### 16.3 Beginner content quality

The curriculum has to be correct at a level where errors are costly. The Week 1 content pilot exposed a source-document numbering problem in Day 1 Guided practice (steps 4–6 misnumbered in the source PDF). The decision was to keep the source verbatim and surface the issue for a founder decision rather than silently rewrite teaching material. This is recorded in QA revision 1.15.

### 16.4 Schema breadth

The platform spans admissions, teaching, assessment and administration. The schema is large because the operation is large. The risk is complexity that outruns the team's ability to operate it. The mitigation is a written QA book with 170 journey checks and a defect register.

### 16.5 Deployment discipline

The QA book requires a revision row for every change and a check that the deployed bundle contains the change. That discipline is a constraint on velocity, but it prevents the most common failure in small projects: believing a fix is live when it is only local.

### 16.6 Evidence limits

There is no formal user research archive in the repository — no interview notes, survey results or usability sessions. The design decisions documented here are supported by the product copy, the QA journeys and the operator's context, not by participant research. I do not claim research that was not done.

---

## 17. Testing and evidence

### 17.1 The QA journey book

`docs/QA-USER-JOURNEYS.md` is the project's primary quality artefact. At version 1.20 it defines **170 journey checks**:

| Group | Checks | Scope |
|---|---|---|
| G — Global | 16 | Shell, navigation, accessibility, cross-cutting behaviour |
| L — Learner and public | 79 | Public pages, registration, payment, learner area |
| S — Staff applicant | 6 | Staff application and review |
| A — Administrator | 69 | Admissions, curriculum, assessment, publication, remediation, settings |

Each row specifies the route, the steps, the expected words on screen, the expected database state, the components involved, the device matrix and the severity. A row passes only when both the interface and the database are correct.

### 17.2 Automated tests

The repository contains ten Vitest test files plus a setup file:

- `content.test.ts`
- `curriculum.test.ts`
- `progress.test.ts`
- `utils.test.ts`
- `validation.test.ts`
- `prose.test.tsx`
- `profile.test.tsx`
- `admin-curriculum.test.tsx`
- `admin-nav.test.tsx`
- `data-table.test.tsx`

QA revision 1.20 records **94 tests, all passing**. The suite grew to ten files after the Phase 2 work. One assertion initially failed because it searched for `role="article"` after the curriculum page moved to the shared `DataTable`, which renders a semantic table; the test now queries table rows and the interface was not changed. The README, QA book and build log all record the same 94-test result.

### 17.3 Captured interface evidence

Fifteen screenshots were captured for this casebook (seven desktop, eight mobile including the open navigation). The harness checked `document.readyState`, the presence of `main`, loaded fonts, loaded images, finite animations and two animation frames before capturing. Every page reported zero runtime errors and no horizontal overflow.

Interaction checks were also run: the FAQ accordion opened and closed on desktop and mobile, and the mobile menu opened into a visible navigation panel. Those checks are recorded in the capture manifest.

### 17.4 What the evidence does not cover

- No authenticated learner session was exercised in this documentation pass.
- No administrator session was exercised in this documentation pass.
- No real payment or receipt was used.
- No load, performance or penetration testing was performed.

---

## 18. Current status

| Surface | Status | Evidence |
|---|---|---|
| Public marketing site | Live at revisions 1.1–1.5 | QA book, deployed URL, commit `abd9d36` |
| Public marketing site, revisions 1.6–1.19 | Built in working tree, not committed or deployed | QA book revision table |
| Enrolment pipeline | Implemented | Source routes, components, migrations |
| Learner area | Implemented | Source routes, QA journeys L-APP-01…14 |
| Administrator area | Implemented | Source routes, QA journeys A-* |
| Curriculum content | Weeks 1–5 published, Weeks 6–8 locked | QA book deployed-state note |
| Week 1 content pilot | 100 corrected sections imported | QA revision 1.15 |
| Profile pages | Implemented; migration 019 applied and verified | QA revision 1.16 |
| Slack notifications | Not complete | QA book scope note |
| Admin review-to-publication leg | Built; live end-to-end pass still needed | QA book status note |

**Release honesty:** The live site is not the whole product. Anyone evaluating the working tree should read the build log's status section before assuming the deployed surface matches the repository.

---

## 19. Limitations and known defects

### 19.1 Open product defects

| ID | Description | Severity | Current position |
|---|---|---|---|
| DEF-01 | `/enrol` always shows the badge "Get started · Registration open", even when registration is closed. The closed banner and disabled button are correct, but the badge contradicts them. | S3 | Open; fix is to drive the badge from `settings.programme_status` |
| DEF-02 | The cohorts page says dates "appear on the public site when configured", but saving a cohort does not update the public settings the site reads. | S3 | Open; sync the settings or change the copy |
| DEF-04 | No interface to remove administrator access. | Operational gap | Open by design; revocation requires SQL |
| DEF-05 | No delete or archive interface for cohorts or registrations. | Operational gap | Accepted for v1; cleanup is by SQL |

### 19.2 Resolved or partially resolved

| ID | Description | Status |
|---|---|---|
| DEF-03 | Staff migration initially not applied | Resolved 2026-11-15; end-to-end staff pass still desirable |
| DEF-06 | Curriculum workspace not exercised with a signed-in administrator | Resolved 2026-11-15; A-CUR-01…10 pass |
| DEF-07 | Publishing a week did not publish its lessons | Resolved by migration `20261115000700_publish_week_lessons.sql`; QA book updated in revision 1.20 |
| DEF-08 | Learner enrolment not linked to an auth user | Resolved 2026-11-15; revision 1.10 records the signed-in learner pass |

### 19.3 Evidence discrepancies

Resolved during the 16 November 2026 QC pass:

1. **DEF-07 and DEF-08 rows are corrected.** The QA book now marks both resolved, with the migration and learner-pass evidence named.
2. **Migration 019 status is consistent.** The QA book header, revision 1.16 and 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, QA book (revision 1.20) and current suite all describe 94 tests, all passing.
4. **README drift is corrected.** The Academy README now lists the implemented public, admin and learner routes, the 19 migrations and the Netlify deployment, and states that the learner platform is working-tree only.

Still open:

5. **No research archive exists.** The repository contains product plans and QA journeys, but no interview notes or usability findings. Design rationale is inferred from the shipped copy and the operator's stated context, and is labelled as such.

### 19.4 Scope limitations

- The product is single-academy and single-programme.
- There is no public learner community inside the app; Slack is the intended cohort space.
- There is no mobile native application.
- There is no automated payment reconciliation.
- There is no self-service refund flow.
- The administrator surface assumes a small, trusted team.

---

## 20. Future roadmap

The following items are supported by the documentation or the defect register. They are not commitments.

### 20.1 Immediate operational fixes

1. Drive the enrolment badge from `programme_status` (DEF-01).
2. Align cohort dates with public settings or correct the admin copy (DEF-02).
3. Document or build administrator revocation (DEF-04).
4. Add archive/delete paths for cohorts and registrations (DEF-05).

### 20.2 Release work

1. Commit and deploy revisions 1.6–1.19 after a full regression pass; revision 1.20 is test and documentation only.
2. Complete the live administrator review-to-publication pass.
3. Exercise the learner profile page with a learner session.
4. Confirm the deployed bundle contains each shipped revision.

### 20.3 Teaching and content

1. Resolve the Day 1 Guided practice numbering issue in the source material.
2. Complete content review for Weeks 2–8 at the same depth as the Week 1 pilot.
3. Finish the Slack notification path.
4. Add clearer learner-facing explanations of assessment criteria.

### 20.4 Product

1. A cohort calendar that reflects real dates on the public site.
2. A learner-visible record of feedback history across assignments.
3. A certificate view tied to completion requirements.
4. An operator dashboard that surfaces ageing items, not just totals.

Any item that changes access, money or learner records should go through the same journey-book revision process that governs the current product.

---

## 21. Reflection

I designed CraftCode Academy around a simple discomfort: it is easy to make an academy look credible and hard to make it honest. The interface could have promised a job, hidden the manual payment step, or simulated instant enrolment. Each of those choices would have produced a smoother demo and a worse product.

The decision I am most confident about is separating registration from enrolment. It makes the funnel longer, but it gives the applicant a reference, gives the academy a review point, and makes the payment step a deliberate act rather than an accident. The status lookup exists because that decision creates a wait, and a wait that is visible is easier to trust.

The decision I would revisit is the breadth of the Phase 2 surface. Lessons, assignments, criteria, reviews, publications and remediation are all real needs, but building them before the first cohort has run means some workflows are designed from the operator's imagination rather than from observed teaching. The QA book is strong, but it tests the product against its own expectations. The next cohort will produce the evidence that matters.

The part of the product I consider most underrated is the copy that states what the programme is not. It is the least exciting section on the site and the one most likely to prevent a mismatch. An academy's reputation is built as much by the people it turns away as by the people it enrols.

---

## 22. Summary

CraftCode Academy is an eight-week, 36-day beginner frontend programme with a reviewed enrolment pipeline, a real learner area and a substantial administrator console. Its design is built on three commitments: explain the programme before asking for money, treat enrolment as a verified process rather than a checkout, and teach with the same rigour as the marketing.

The public site is live at revisions 1.1–1.5. The full Phase 2 platform — curriculum, submissions, assessments, reviews, remediation, profiles — is implemented and tested in the working tree, with a small, documented set of operational defects. Migrations 001–012 and 019 are recorded as applied and verified; the Week 1 content repair is recorded as imported in QA revision 1.15, while the 014–018 repair files remain in the working tree. The Phase 2 application code is not deployed. The product's strongest asset is not its visual identity; it is the honesty of its operating model, which is visible in the copy, enforced in the database and recorded in the QA book.

---

### Evidence index

| Evidence | Location |
|---|---|
| QA journey book (v1.20) | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode\docs\QA-USER-JOURNEYS.md` |
| Curriculum data | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode\src\data\curriculum.ts` |
| Route map | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode\src\App.tsx` |
| Design tokens | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode\tailwind.config.ts` |
| Database schema | `C:\Users\HelsaGrace\Desktop\Skills Acquisition\craftcode\supabase\migrations\` |
| Screenshots and manifest | [`PROJECT_ASSETS`](./PROJECT_ASSETS) |
| Engineering record | [PROJECT_BUILD_LOG.md](./PROJECT_BUILD_LOG.md) |
