Co-VibeDocs

Engineering

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.

View as .md