Check the machine before installing

From the repository root:

bun run setup:doctor

Expected result shape:

PASS  bun                 Found Bun 1.3.9
PASS  lockfile            bun.lock matches the root workspace
WARN  dependencies        node_modules is missing
PASS  docker              Docker daemon is reachable
PASS  port:8787           Port is available

The exact list depends on your machine. Missing node_modules before installation is normal. A missing Bun version, unavailable Docker daemon, or occupied required port needs attention.

Install the exact workspace graph

bun install --frozen-lockfile

Expected result shape:

bun install v1.3.9
Resolving dependencies
Saved lockfile

The important result is that the command exits successfully without changing bun.lock.

If Bun proposes a lockfile change, stop and check the Bun version before committing anything.

Bootstrap local infrastructure, environment, and data

bun run dev:bootstrap

This runs the repository-owned sequence:

dev:infra
→ wait for Postgres and LocalStack
→ dev:env from local development templates
→ migrate db-main
→ migrate db-auth
→ seed db-main
→ seed local superadmin accounts

This local path does not require AWS Secrets Manager. bun run secrets is a separate AWS-backed path for managed values.

Start the API and authentication

Use two terminals. Each command is long-running, so leave both terminals open.

Terminal 1 — API gateway:

cd monorepo/apps/checkbox-api
bun run dev

Terminal 2 — authentication:

cd monorepo/apps/auth-web
bun run dev

Expected result shape:

checkbox-api: listening on http://localhost:8787
auth-web:     Local: http://localhost:5176/

The exact wording depends on the app runner; the ports are the useful check. If either terminal exits, capture the first error before trying another command.

Start the admin web

Open a third terminal. Keep the API and authentication terminals running.

cd monorepo/apps/admin-web
bun run dev

Expected result:

admin-web:    Local: http://localhost:5173/

If the terminal exits, check the compile output, missing environment variables, and whether port 5173 is already in use. Do not proceed to the browser until the process stays running.

When all three processes are alive, continue to the API health check before opening the application.

Sign in locally without sharing credentials

Use the local account generated by the approved seed path when the exercise requires a role-specific workflow.

bun run monorepo/scripts/seed-diwamail-accounts.ts

Expected result shape:

Created local-only accounts
Wrote credentials to outputs/diwamail-accounts/

Read credentials locally. Do not paste them into the handbook, evidence, chat, screenshots, or commits. If authentication redirects to the wrong host, check AUTH_API_URL, AUTH_WEB_URL, and ALLOWED_REDIRECT_ORIGINS.

Start from a known branch state

git fetch origin main
git switch main
git pull --ff-only origin main
git status --short --branch
git branch --show-current

Expected clean shape:

## main...origin/main
main

If switching or pulling would overwrite local work, stop. If you see modified files that are not yours, preserve them. Do not use git reset --hard or git checkout -- to make the tree look clean.

Create a short-lived working branch

For the exercise:

git switch -c feat/turnover-dashboard-marker
git branch --show-current

Expected result:

Switched to a new branch 'feat/turnover-dashboard-marker'
feat/turnover-dashboard-marker

If the branch already exists, use git switch feat/turnover-dashboard-marker only after confirming it contains the intended work. Do not reuse another developer's branch.

Find the component that owns the visible text

From the repository root:

rg -n --fixed-strings 'Recent Questions' monorepo

Expected result shape:

monorepo/packages/core/feat-admin-app-ui/src/feat-dashboard/pages/overview.page.tsx:...

Open the matching file and confirm the text is inside the dashboard component. A search result is a lead; reading the surrounding component is the confirmation.

Make one visible change

Edit only:

monorepo/packages/core/feat-admin-app-ui/src/feat-dashboard/pages/overview.page.tsx

Change:

-Recent Questions
+Recent Questions · Turnover Check

Do not change data, API requests, styles, configuration, dependencies, or unrelated files for this exercise.

Inspect the intended diff

git diff -- monorepo/packages/core/feat-admin-app-ui/src/feat-dashboard/pages/overview.page.tsx

Expected shape:

- Recent Questions
+ Recent Questions · Turnover Check

If the diff contains generated files, env files, lockfile changes, or unrelated edits, stop and separate those changes before staging.

Commit only the intended file

git add monorepo/packages/core/feat-admin-app-ui/src/feat-dashboard/pages/overview.page.tsx
git diff --cached --check
git commit -m "chore: add dashboard turnover marker"
git rev-parse HEAD

Expected result shape:

[feat/turnover-dashboard-marker abc1234] chore: add dashboard turnover marker
1 file changed, 1 insertion(+), 1 deletion(+)
<40-character commit SHA>

If the staged diff is wrong, unstage the file with git restore --staged . Do not rewrite or delete unrelated working changes.

Route config points to the shell

The route file registers which app module receives /dashboard:

// monorepo/apps/admin-web/app/routes.ts
...prefix("dashboard", [
  index("features/feat-dashboard/pages/overview-shell.page.tsx"),
]),

The route config decides which shell loads. It does not own the dashboard's domain UI or database query.

The shell injects runtime services

The shell reads environment/runtime context, builds the service, and passes it into the package page:

// overview-shell.page.tsx
const dashboardService = useMemo(
  (): DashboardService => ({
    getEncoderDashboard: () =>
      fetchEncoderDashboard({ baseUrl: apiBaseUrl }),
  }),
  [apiBaseUrl],
);

return <OverviewPage user={user} dashboardService={dashboardService} onNavigate={navigate} />;

This is why the reusable page can render UI without knowing which environment-specific API URL it should use.

The browser adapter owns transport details

The adapter turns a service call into an HTTP request and returns typed application data:

// monorepo/apps/admin-web/app/features/feat-dashboard/api/encoder-dashboard.api.ts
export async function fetchEncoderDashboard(
  options: EncoderDashboardFetcherOptions = {},
): Promise<EncoderDashboard> {
  const fullPath = options.baseUrl
    ? `${options.baseUrl}/dashboard/encoder`
    : "/dashboard/encoder";
  const response = await apiClient<EncoderDashboardResponse>({
    path: fullPath,
  });
  return response.data;
}

It is a browser-side adapter. It does not decide database scope or authorization rules.

The API actor owns auth and durable reads

The domain route receives the request after gateway dispatch:

// monorepo/packages/core/api-admin/src/core/routes/dashboard.ts
app.get("/dashboard/encoder", authMiddleware, async (c) => {
  const user = c.get("user");
  const { dbMain } = c.get("dbContext");

  // authorize, query dbMain, then return the response contract
});

The gateway routes traffic. api-admin owns admin behavior. dbMain owns the durable data boundary.

Add a feature without crossing package boundaries

For domain behavior, follow the existing package shape:

monorepo/packages/core/feat-<domain>/src/features/<feature>/
├── contract.ts
├── client.ts
├── methods/
│   ├── index.ts
│   └── <method>.ts
└── index.ts

The usual order is:

1. Define Zod contracts and public types.
2. Implement one focused method per file.
3. Inject dbMain, dbAuth, or services.
4. Compose the client.
5. Export only the public surface.

Add a web route: exact verification path

After creating a page file and registering it in app/routes.ts:

cd monorepo/apps/admin-web
bun run check-types
bun run dev

Expected type-check shape:

react-router typegen completed
tsc --build --noEmit

Expected browser result:

GET http://localhost:5173/<route>
200 OK

If route types fail, rerun the affected app's check-types; do not manually edit generated route metadata.

Add an API route: exact verification path

Choose the actor first:

auth behavior       → packages/core/api-auth
admin behavior      → packages/core/api-admin
school behavior     → packages/core/api-school
student behavior    → packages/core/api-learn

Then verify through the gateway:

cd monorepo/apps/checkbox-api
bun run dev
curl -i http://localhost:8787/health

Expected result:

HTTP/1.1 200 OK
content-type: application/json
{"status":"ok","service":"checkbox-api"}

Do not test only the actor's internal route if the user reaches it through checkbox-api.

Run focused checks first

From a touched package:

bun run check
bun run check-types

From the repository root:

bun run test:unit

Expected result shape:

Checked files: <count>
No diagnostics found
<test count> pass

Run bun run ci before handing back a broad product change. It includes repository checks, boundaries, type checks, and unit tests.

Write a pure test beside the source

Typical shape:

src/utils/parse-value.ts
src/utils/parse-value.spec.ts

The test should:

1. import the public function;
2. provide a small input;
3. assert the output or error contract;
4. avoid mocking dependencies for pure behavior.

Run only the file while iterating:

bun test path/to/parse-value.spec.ts

Expected result:

pass  path/to/parse-value.spec.ts

Generate a migration from its schema owner

Use the package that owns the schema:

cd monorepo/packages/core/db-main
bun run migrate:generate -- --name=<short-description>

For auth schema changes:

cd monorepo/packages/core/db-auth
bun run migrate:generate -- --name=<short-description>

Expected result shape:

Created kysely migration at src/migrations/<timestamp>_<short-description>.ts

Inspect a generated migration before applying it

For db-main, the command may also report the generated Drizzle migration. If it reports no schema changes, inspect the schema diff before continuing.

Before applying it:

• Confirm the generated file matches the intended schema change.
• Run the owning package checks.
• Confirm the target environment before applying it.
• Use the generated migration metadata and naming; do not create migration files manually.

Start at the public testing commands

# code behavior
bun run test:unit

# browser workflow
bun run test:e2e -- --rows TCH-001 --workers 1 --run-id teacher-smoke

# deployed capacity
bun run test:load -- --profile smoke

The -- separator belongs to Bun. Everything after it is forwarded to the repository-owned runner.

Use the live command help when a flag is unfamiliar:

bun run test:e2e -- --help
bun run test:load -- --help

Start with test:*. The lower-level uat:*, AWS, and direct k6 commands are escape hatches for debugging the machinery underneath.

Unit tests: fast feedback for code behavior

# all repository-owned unit tests
bun run test:unit

# one file while debugging
bun test path/to/file.spec.ts

Unit tests cover pure functions, contracts, helpers, and script behavior. They should answer one small question without needing a browser, UAT services, AWS, or a live database.

They do not prove that a route is registered, a browser can sign in, or a deployed image can handle traffic. Move to E2E when the user workflow matters.

Checks sit beside unit tests

bun run check         # formatting, workspace rules, boundaries, package checks
bun run check-types   # TypeScript across the workspaces
bun run ci            # check + boundaries + types + unit tests

Use the narrowest useful command first, then the full suite before submitting a change:

changed pure helper  → focused bun test
changed package/API  → package check + check-types
changed behavior     → bun run ci, then E2E if a browser path is involved

The full local CI command does not run Playwright or AWS load tests. Those are separate because they need different environments and credentials.

Inspect the browser request

1. Open browser developer tools.
2. Select Network.
3. Reload the page.
4. Filter for dashboard/encoder.
5. Record method, path, status, and duration.

Expected successful shape:

GET /api/admin/dashboard/encoder
200 OK

Do not copy cookies, authorization headers, question content, or personal data into shared evidence.

Reproduce the public API health boundary

curl -i http://localhost:8787/health

Expected result:

HTTP/1.1 200 OK
content-type: application/json
{"status":"ok","service":"checkbox-api"}

Health proves the gateway is reachable. It does not prove the authenticated feature request succeeds.

Find the source boundary with exact text

rg -n --fixed-strings 'Recent Questions' monorepo
rg -n 'dashboard/encoder' monorepo/apps monorepo/packages

Expected locations include:

feat-admin-app-ui/.../overview.page.tsx
admin-web/.../encoder-dashboard.api.ts
api-admin/.../routes/dashboard.ts

Read the imports and caller chain around each match. A filename match alone is not proof of active wiring.

Repair the local loop

Use this order:

git status --short
bun run check
bun run check-types
bun test path/to/focused.spec.ts

Then restart only the affected process. If the failure is caused by stale local data, use the documented reset path; if it is caused by source, preserve the first compiler or test error.

Expected recovery result:

The smallest failed command now passes
The affected process restarts
The browser workflow is rechecked

Configure CodeCommit for this repository

After cloning with an AWS identity that can access the repository:

bun run aws:codecommit:helper -- --apply-local-git-config
git remote -v
git fetch origin --prune

Expected result shape:

origin  https://git-codecommit.ap-southeast-1.amazonaws.com/v1/repos/diwa-checkbox (fetch)
origin  https://git-codecommit.ap-southeast-1.amazonaws.com/v1/repos/diwa-checkbox (push)

The helper changes this repository's .git/config. If fetch fails, check AWS identity, CodeCommit permission, profile, and the repository-local helper before changing global Git settings.

Start a feature from the future staging branch

git fetch origin staging
git switch --track -c staging origin/staging
git switch -c feat/<short-description>
git branch --show-current

Expected result:

branch 'staging' set up to track 'origin/staging'.
Switched to a new branch 'feat/<short-description>'
feat/<short-description>

If staging already exists locally, use git switch staging followed by git pull --ff-only origin staging, then create the feature branch. If origin/staging does not exist, this future process has not been provisioned. Stop and use the current branch policy; do not create an environment promise from a missing branch.

Push a feature branch

After local checks pass:

git status --short --branch
git diff --cached --check
git push -u origin feat/<short-description>
git ls-remote origin refs/heads/feat/<short-description>

Expected result shape:

branch 'feat/<short-description>' set up to track 'origin/feat/<short-description>'
<commit SHA>  refs/heads/feat/<short-description>

If push is rejected, preserve the error. Common causes are expired AWS credentials, missing CodeCommit permission, a remote branch that moved, or a protected destination. Do not force-push a shared branch.

Inspect the pull request before approval

aws --region ap-southeast-1 codecommit get-pull-request \
  --pull-request-id <pr-id> \
  --query 'pullRequest.{status:pullRequestStatus,source:pullRequestTargets[0].sourceReference,destination:pullRequestTargets[0].destinationReference,revision:pullRequestTargets[0].sourceCommit}'

Expected result shape:

{
  "status": "OPEN",
  "source": "feat/<short-description>",
  "destination": "staging",
  "revision": "<full commit SHA>"
}

Reviewers should confirm the source SHA, checks, migration compatibility, UAT scope, and rollback concern before approval.

Promote the tested revision into main

Create a second PR:

aws --region ap-southeast-1 codecommit create-pull-request \
  --title "Promote staging release" \
  --description "Promotes the tested staging revision to production" \
  --targets "repositoryName=diwa-checkbox,sourceReference=staging,destinationReference=main" \
  --query 'pullRequest.pullRequestId' \
  --output text

After approvals, use the repository's approved merge method. Prefer fast-forward when it preserves the tested SHA:

aws --region ap-southeast-1 codecommit merge-pull-request-by-fast-forward \
  --pull-request-id <promotion-pr-id> \
  --repository-name diwa-checkbox

Expected result includes a merged status and commit identity. If fast-forward is impossible, stop and reconcile history rather than silently cherry-picking.

Hotfix and rollback policy

For a production incident:

1. Branch from the known production revision or follow the approved recovery runbook.
2. Make the smallest safe fix.
3. Validate locally.
4. Submit a CodeCommit PR to the approved release branch.
5. Promote the fix through staging when the incident allows it.
6. After the production merge, reconcile the fix back into staging.

Do not reset a shared branch, delete an accepted tag, or deploy a mutable latest image as a rollback.

Current UAT release path

For the current repository process, an accepted update to CodeCommit main triggers the AWS-native pipeline:

CodeCommit main
  → EventBridge
  → CodePipeline
  → CodeBuild
  → ECR images
  → EC2 deployment through SSM
  → health and workflow checks

The future staging workflow in the bonus section is not active unless DIWA provisions the separate environment and branch trigger.

Find the pipeline execution for one SHA

git rev-parse origin/main

aws --region ap-southeast-1 codepipeline list-pipeline-executions \
  --pipeline-name diwa-checkbox-production-deploy \
  --max-results 10

Expected result contains source revision IDs and an execution status such as InProgress, Succeeded, or Failed.

If no execution matches the accepted SHA, do not select the newest execution. Confirm the source revision, pipeline trigger, and CodeCommit branch.

Verify an image tag and digest

aws --region ap-southeast-1 ecr describe-images \
  --repository-name diwa-checkbox-admin-web \
  --image-ids imageTag=<12-character-tag> \
  --query 'imageDetails[0].{digest:imageDigest,pushedAt:imagePushedAt}' \
  --output table

Expected result includes one digest and a push time.

If the tag is missing, expired, or resolves to a different digest than the accepted release record, stop. Do not deploy it as a known-good image.

Verify public health and the user workflow

bun run aws:smoke-health -- --environment bsp

Then use an approved UAT account to verify the changed workflow in the browser.

Expected evidence:

Health:        all required public surfaces healthy
Workflow:      intended route loads and changed behavior is visible
Revision:      accepted SHA/tag/digest recorded
Residual risk: documented or none

Health is necessary but not sufficient. A green health endpoint does not prove login, authorization, data correctness, or the target workflow.

Recovery has a stop condition

Before any recovery action, confirm:

[ ] intended AWS account and region
[ ] intended environment
[ ] approved operator and change window
[ ] known-good image digest
[ ] schema compatibility
[ ] rollback access
[ ] exact post-recovery checks

If the maintained helper reconciles more services, runs more migrations, or pulls by mutable tag than the incident requires, do not use it as a narrow recovery command. Record the blocker and keep the exercise tabletop-only.