Tech Stack

Overview

Tech Stack gives a Default Recommendation per project type as the starting point for routine work. A trigger classifier decides when that is not enough: a new project or service, a component in a different domain from the incumbent stack, a stack migration, or an explicit operator request produces a Stack Proposal with 2–3 candidates, explicit trade-offs and a recommendation. L1 tasks and routine same-domain work skip it; an ambiguous case defaults to a proposal. The operator chooses, and the choice is recorded as a decision note in the plan and bound by the immutability contract. Core principles: simplicity over complexity, performance over convenience, widely adopted tools with strong communities.

Default Recommendations (Selection)

• Static Landing — HTML, CSS, Tailwind, Alpine.js (optional). No SPA.
• Static Multi-Page — PHP, HTML, Tailwind. SSR templates. Docker required.
• Web Frontend (SEO) — Next.js, React, Tailwind, shadcn/ui, Vite, pnpm, Vitest, Playwright.
• SPA / Dashboard — Vite, React or Vue, Tailwind, TanStack Query, Vitest.
• Microservice API — NestJS, Fastify, PostgreSQL, Prisma, Redis, NATS.
• Python API — FastAPI, uvicorn, uv, ruff, pydantic, sqlalchemy, alembic, pytest.
• AI/LLM — Python, FastAPI, uv, ruff, OpenAI/OpenRouter SDK, Redis.

Each row also lists viable alternatives and a verifiable “when to reconsider” test; further rows cover high-load and gateway APIs, RAG and search, real-time, background and event-driven work, media, monorepos, auth, prototyping and CLI or systems tools.

Recommended Toolchains

Python: uv (dependencies), ruff (lint + format), pytest (testing). Node/TypeScript: pnpm, TypeScript, eslint + prettier, vitest, playwright for E2E. These are quality-floor defaults — deviate with a one-line rationale. Docker is used for backend services.

Architecture Guidance

Guidance, not mandates: each rule carries a rationale, and you deviate when the rationale does not apply.

• No SPA where HTML suffices
• Fastify is the default for Node.js HTTP (alternatives: Hono, Express)
• Redis as default cache
• Event-driven systems use NATS or Kafka
• PHP is for SSR/template reuse only
• Queues are not WebSockets; WebRTC is for media only
• No exotic libraries without justification

Infrastructure & Backups

Server backups use restic + Backblaze B2 (native backend, client-side encryption, dedup, snapshots). Database backups use per-engine tooling (pg_dump, mysqldump) piped into restic.

Dependency Version Policy

Always install the latest stable (LTS where applicable) version. If a new major has breaking changes, adapt the code — do not downgrade. Run pnpm outdated (or uv pip list --outdated) immediately after scaffold and after every added dependency. AI hallucination guard: verify latest versions via npm view or pip index versions before specifying in config files.