# Stack Decision

Agents should use this stack unless a blocking issue is found.

## Default Stack

- App: Next.js with App Router
- Language: TypeScript
- Support language: Python where it clearly helps
- Database: PostgreSQL for local product use, rehearsal, and `co-vibe.dev`
  production
- Query layer: `pg` for PostgreSQL through a sync runtime bridge while
  repositories move to native async `pg`
- Auth: WorkOS AuthKit first
- Auth fallback: Clerk
- Agent tools: stdio MCP bridge plus JSON endpoint
- Browser QA: Playwright
- Package manager: use the package manager created by the scaffold

## Why This Stack

Next.js gives one app for UI and API routes.

PostgreSQL is the product database. Local dogfood should use a local Postgres
container or a managed test database, not a second app-state source of truth.

The current repository surface still uses sync database calls, so PostgreSQL
runs through a `pg` worker bridge while a cleanup pass converts repositories to
native async `pg`. `npm run db:postgres:init` initializes schema and policies,
`npm run smoke:postgres` covers schema setup and isolation policy smoke, and
`npm run smoke:postgres:runtime` proves repository calls run against PostgreSQL
with tenant/workspace scope. Unit and browser tests use PostgreSQL as well.

WorkOS AuthKit is the first auth choice because this product is team/workspace shaped.

Clerk is fallback because it is fast to wire into Next.js and has strong prebuilt UI.

The stdio bridge gives real MCP clients an installable path while the JSON endpoint keeps browser/API tests simple.

Playwright proves the UI works like a user would use it.

Python is allowed for jobs where it is the better tool:

- overlap scoring experiments
- audit scripts
- weekly summary generation helpers
- data import/export
- statistics and usage analysis
- maintenance scripts
- security or repo-health checks

Do not split the core product across languages for no reason.

The app, UI, MCP contract, auth, and main database writes should stay easy to follow.

If Python is used, document:

- why Python was chosen
- where the script lives
- how to run it
- what inputs and outputs it uses
- how it is tested

## Auth Decision Rule

Use WorkOS AuthKit if it can be wired in cleanly during the loop.

Use Clerk only if WorkOS blocks progress.

Do not reintroduce local-dev identity as production auth. WorkOS remains the
hosted auth path, and any external verification gap must be listed in
`reports/morning-report.md`.

## Open Source Reuse

Before implementing MCP server patterns, auth wiring, or overlap search from scratch, search for trusted open-source examples.

Trusted means:

- at least 1,000 stars when a comparable project exists
- compatible license
- active maintenance
- no obvious security risk

Do not copy code blindly.

Write what was reused or studied in the morning report.