Readme

Comprehensive, file-per-flow documentation of every user journey the Hackorda QA platform supports. Each flow doc is self-contained — QA engineers can pick up one file and (a) verify the flow on production or (b) write automated tests against it without reading anything else.

If you're looking for a 1-page overview, see Feature Matrix. For architecture, see Test Cycles. This directory is the operational test plan.

---

Who this is for

• QA engineers — verify what works, build a regression suite, write Playwright specs against shipped flows.
• Product owners — understand exactly what a flow guarantees, what events fire, and where coverage gaps live.
• Engineers — confirm a change didn't accidentally break a contract before merging.

---

How to read a flow doc

Every flow file follows the structure in Template. Skim the header for status / actors / preconditions, then jump to:

• Steps table — the canonical happy path. UI surface → API call → DB write → notification → event, in order.
• Acceptance criteria — Given/When/Then statements that map 1:1 to test cases.
• Negative paths — failure modes the system must handle gracefully.
• Manual QA checklist — discrete checkboxes you can tick on a real environment.
• Automated test stubs — outline a Playwright spec covers.

---

How to use these docs

As a QA engineer doing manual verification

1. Open Index, pick a flow ranked 🟢 ready to test.
2. Read the Preconditions section and seed any needed data (most flows reference fixtures from src/db/seed-test-cycles-bootstrap.ts or src/db/seed-hackorda-qa-cycle.ts).
3. Walk through the Manual QA checklist on https://hackorda.kz (production) or your local dev server.
4. Log defects as bug reports linked to the flow ID (e.g. F-08-bug-1).

As a QA engineer building automation

1. Pick a flow tagged ✅ shipped + stable.
2. Read the Steps table — the API calls listed are exactly what your spec should assert against.
3. Use the Automated test stubs section as the outline for your spec.
4. Phase 4 of the Playwright suite (under tests/e2e/) is the target home for these.

As an engineer adding a feature

1. Copy TEMPLATE.md to F-NN-your-flow.md (next free number).
2. Fill it in before writing the feature (helps you catch design holes).
3. Add a row to INDEX.md.
4. Mark the flow 🟡 in progress until it ships.
5. When you ship, mark it ✅ and tell QA.

---

Flow ID convention

F-NN where NN is two digits, zero-padded. Numbers are stable forever — once assigned, never reused. Deleted flows leave a tombstone row in INDEX.md so old test runs that reference the ID still make sense.

---

Status legend

---

Conventions used inside flow docs

• actor in steps tables = the user driving the action.
• actor_role is the user's system role unless prefixed with cycle: for per-cycle role (e.g. cycle:lead).
• DB writes use the table name from src/db/schema.ts.
• API calls use the route path from src/app/api/....
• Events use the domain.action taxonomy from Feature Matrix §4.

---

Test data baseline

Every flow assumes the following seed exists (it does, on production and local dev — seed:tc-bootstrap + seed:tc-onboarding create it):

• Organization — Hackorda (type=internal)
• Product — Hackorda Web (discipline=web_app, has URL)
• Version — v0.1.0
• Cycle — Hackorda Onboarding — QA shake-down (status=active, open_to_self_join=true)
• Cycle docs — onboarding handbook + 52 test cases (auto-synced from docs/qa/*.md)

Most flows reference this baseline as their starting state. If you need a clean slate for a specific test, document the seed reset in the flow's Preconditions section.