AI_template/docs/examples/RECOMMENDATIONS-example.md

Project-Specific Recommendations & Overrides (EXAMPLE)

This is a filled-in example for a compliance document classifier (Archetype C). Copy RECOMMENDATIONS.md from the repo root and replace placeholders with your values.

---

1. Project Context

• Domain / product type: Compliance document classifier for financial institutions
• Chosen archetype: C — Classification / Decision Support Pipeline
• Modules in scope: core AI, integrations, pipeline, human feedback, events, reporting, multi-tenancy, billing
• Primary users: compliance officers, team leads, auditors
• Key success metrics: classification accuracy > 95%, p95 latency < 3s, < 5% manual reviews
• Current phase: Phase 1
• Repos/services in scope: monorepo (apps/web, apps/api, packages/shared)

2. Locked Stack Decisions

Frontend

• Framework: Next.js 15 (App Router)
• Language: TypeScript 5.7
• Styling: Tailwind CSS 4.x + shadcn/ui
• Server/Client data layer: React Query v5
• Forms & validation: React Hook Form + Zod
• Auth client: Clerk

Backend

• Runtime/language: Node.js 22 LTS + TypeScript 5.7
• Framework: Fastify
• Database: PostgreSQL 16 (vector search: pgvector)
• ORM: Drizzle
• Queues/workers: BullMQ (Redis 7)
• LLM provider & helper: Single callLLM() abstraction, provider: Anthropic (Claude Sonnet)
• File/storage: Cloudflare R2

Infra / DevOps

• Hosting/deploy: Vercel (web) + Railway (api + workers)
• CI/CD: GitHub Actions
• Observability: Sentry (errors) + Axiom (logs)
• Environments: dev / staging / prod

3. Non-Negotiable Constraints

• Compliance/regulation: SOC2, GDPR (EU data residency)
• Data residency/retention: EU-only, 7-year retention for audit logs
• Performance/SLOs: p95 classification < 3s, API p99 < 500ms
• Cost limits: LLM budget $2000/month, infra cap $500/month
• Target platforms: Chrome/Firefox/Safari latest 2 versions, desktop-first
• Repository constraints: no npm run dev in CI; all merges via PR with at least 1 approval

4. Deviations From Template

• Using Fastify instead of Express → better async performance and schema validation built-in → no migration plan needed (greenfield)
• Using Drizzle instead of Prisma → lighter, better SQL control for complex queries → can migrate via schema dump if needed
• Skipping i18n in Phase 2 → single-locale MVP (English), will add next-intl in Phase 3

5. Open Questions / To Confirm

• Vector embedding model choice (OpenAI ada-002 vs Cohere) → backend lead → Phase 1
• Exact Clerk plan and SSO requirements → product owner → Phase 1

6. Change Log

• 2025-01-15: Locked Fastify + Drizzle (ADR-0001)
• 2025-01-20: Chose Cloudflare R2 over S3 (cost + EU edge)
• 2025-02-01: Set LLM budget cap at $2000/month

7. Architecture Decision Records (ADRs)

• docs/adr/0001-fastify-over-express.md — accepted
• docs/adr/0002-drizzle-over-prisma.md — accepted
• docs/adr/0003-cloudflare-r2-storage.md — accepted