# Project-Specific Recommendations & Overrides

This file is the project-specific layer on top of the generic template.  
Humans and AI agents should treat it as the **single place to record locked decisions, non‑negotiable constraints, and intentional deviations** from `docs/` guidance.

Update this file whenever you make a decision that changes the stack, scope, constraints, or any recommendation in `docs/`.

---

## 1. Project Context (fill in)
- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_  
- **Chosen archetype:** _[A–E from `/docs/archetypes.md`]_  
- **Modules in scope:** _[core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]_  
- **Primary users:** _[roles/personas]_  
- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_  
- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_  
- **Repos/services in scope:** _[monorepo, separate FE/BE, workers, etc.]_

## 2. Locked Stack Decisions (override template here)
If a choice is not listed here, the default recommendations in `docs/` apply.

**Frontend**
- **Framework:** _Next.js (App Router)_ / _other_  
- **Language:** _TypeScript_ / _other_  
- **Styling:** _Tailwind CSS_ / _other_  
- **Server/Client data layer:** _React Query / SWR / other_  
- **Forms & validation:** _React Hook Form + Zod_ / _other_  
- **Auth client:** _Clerk / Auth.js / other_

**Backend**
- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_  
- **Framework:** _Express / Fastify / other_  
- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_)  
- **Queues/workers:** _BullMQ (Redis)_ / _other_  
- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_  
- **File/storage:** _S3/Supabase Storage/local_ / _other_

**Infra / DevOps**
- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_  
- **CI/CD:** _[GitHub Actions/GitLab/etc.]_  
- **Observability:** _[Sentry/OTel/Prometheus/etc.]_  
- **Environments:** _dev/stage/prod_ (or specify)

## 3. Non‑Negotiable Constraints (add to RULES scope)
- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_  
- **Data residency/retention:** _[regions, retention window]_  
- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_  
- **Cost limits:** _[monthly LLM budget, infra cap]_  
- **Target platforms:** _[browsers/devices, locales]_  
- **Repository constraints:** _[additional forbidden commands, branching rules, etc.]_

## 4. Deviations From Template (explicit trade-offs)
List any intentional departures from `docs/` recommendations and why.

- _[Decision]_ → _[Why]_ → _[Migration/rollback plan if relevant]_

## 5. Open Questions / To Confirm
- _[Unresolved item]_ → _[owner]_ → _[ETA]_

## 6. Change Log (optional)
- _YYYY‑MM‑DD_: _[decision summary]_  

## 7. Architecture Decision Records (ADRs)
Record major decisions and their rationale in `docs/adr/`.

Example ADRs you may need:
- _ADR: modular monolith vs microservices_
- _ADR: vector storage choice (pgvector vs external)_
- _ADR: billing model/provider_
- _ADR: RAG strategy and retrieval stack_
- _ADR: auth/tenancy model_

Once accepted, link ADRs here:
- `docs/adr/0001-<title>.md` — _accepted_