Guided code tour

Use this route through the repository to turn the architecture map into source-level understanding. Each stop is intentionally small enough to review in one sitting.

Stop 1: the durable model

Read: packages/db/prisma/schema.prisma

Look for:

• relationship membership timestamps;
• response scope identity;
• lifecycle timestamps instead of destructive state;
• indexes that mirror actual reads;
• one-to-one quality review and content hash.

Then open the migrations that add relationship-integrity triggers. Ask which rules Prisma expresses and which require PostgreSQL itself.

Stop 2: one domain operation

Read: packages/core/src/relationships.ts

Start with invitation acceptance or response upsert. Trace:

1. input normalization;
2. active membership check;
3. transaction boundary;
4. conditional update or upsert;
5. notification side effect;
6. return state.

Notice that the functions accept a Prisma transaction client. That makes composition atomic without coupling callers to route behavior.

type RelationshipDb = typeof prisma | Prisma.TransactionClient

export async function someOperation(input: Input, db: RelationshipDb = prisma) {
  // same operation works standalone or inside a larger transaction
}

Stop 3: route as adapter

Read: one route under apps/web/app/api/v1/ and its colocated spec.

Identify what belongs to HTTP:

• parse path and body;
• establish authentication;
• map domain errors to status codes;
• shape the documented response.

Then identify what does not belong there: relationship invariants, response ownership, or database race handling.

Stop 4: server-rendered presentation

Read:

• apps/web/app/(app)/prompts/page.tsx
• apps/web/app/(app)/prompts/[promptId]/promptDetailData.ts
• apps/web/app/(app)/prompts/DailyConversationCard.tsx

Observe the split between data acquisition, presentation state, and interactive client islands. Check loading files next to each route to see how unavoidable waits are explained.

Stop 5: navigation performance

Read: apps/web/app/_components/Navigation/

The folder contains intent prefetch, route warming, pending indicators, focus management, history tracking, and measured navigation performance. Review them as a coordinated user-flow system rather than isolated UI helpers.

Ask:

• Which links prefetch and when?
• How does the UI show that intent was received?
• What happens to keyboard focus after navigation?
• Which metrics distinguish network wait from rendering?

Stop 6: admin lifecycle safety

Read: apps/admin/app/prompts/

Follow draft → quality review → schedule → publish → archive. Notice how:

• generated content records provenance;
• review records the exact content hash;
• bulk transitions validate every selected prompt;
• admin mutations record audit metadata;
• public prompt cache revalidation happens after mutation.

Stop 7: typed queue seam

Read:

• packages/queue/src/index.ts
• apps/worker/src/index.ts
• apps/worker/src/lifecycle.ts
• apps/worker/src/health.ts

Trace the differences between producer and worker connections, then follow shutdown from signal to worker, Redis, and HTTP health closure.

Stop 8: the release as code

Read in order:

1. Dockerfile
2. compose.coolify-pr.yaml
3. compose.coolify.yaml
4. scripts/run-coolify-pr-ci.mjs
5. scripts/watch-coolify-deploy.mjs

The Dockerfile proves build-time quality. PR Compose proves migrations and queue integration on disposable services. Production Compose expresses startup order and health. The watcher connects Git main to the private Coolify control plane.

Stop 9: developer feedback

Read:

• scripts/test-changed-plan.mjs
• scripts/run-next-build.mjs
• scripts/dev-doctor.mjs
• their *.spec.mjs files.

These scripts are worth studying because developer experience is also architecture: fast and trustworthy feedback changes how safely the system can evolve.

A review exercise

Choose one user story—invite a partner, answer a prompt, reveal a response, or schedule a prompt—and make a table:

Layer	File/function	Trust established	Failure behavior
UI
Route/Action
Auth
Domain
PostgreSQL
Side effects
Test/release proof

If one row is hard to fill in, that is the next useful code-reading question.

Return to the system map or use local search to investigate a concept across lessons.