Architecture Review & Refactoring

# ADR-XXXX: <Decision Title>

## Status
Proposed | Accepted | Superseded

## Context
What pressure or constraint caused this decision? Include observed evidence.

## Decision
What are we choosing?

## Alternatives Considered
- Alternative A
- Alternative B

## Consequences
### Positive
- ...

### Negative / Cost

# TaskFlow Architecture Map - Phase 35

## Primary request path

Browser -> Next.js -> authenticated API client -> NestJS/Fastify -> auth guard -> authorization -> application service -> repository -> Prisma -> PostgreSQL

## Supporting infrastructure

- Supabase Auth: external identity/session provider
- Supabase Storage: attachment bytes; PostgreSQL stores attachment meaning/metadata
- Supabase Realtime: freshness signal; HTTP/NestJS remains authoritative
- TanStack Query: browser server-state cache
- React Hook Form: unsaved form draft state
- GitHub Actions + Docker + deployment platforms: delivery/operations
- Sentry/logs/metrics/traces: observability

## Dependency rules

1. Controllers do not query Prisma directly.
2. Services own business workflow and policy decisions.

# Architecture Review Checklist

## Backend
- [ ] Controllers stay transport-focused.
- [ ] Services own business workflow/invariants.
- [ ] Repositories hide meaningful persistence mechanics.
- [ ] Transactions match business atomicity.
- [ ] HTTP exceptions do not leak into persistence adapters.

## Frontend
- [ ] Server state is not duplicated into local state.
- [ ] URL state remains deep-linkable.
- [ ] Form drafts stay in React Hook Form.
- [ ] Client boundaries are as small as practical.
- [ ] Auth/session state is not duplicated.

## Security
- [ ] Identity comes from verified token claims.
- [ ] Tenant scope is enforced server-side.
- [ ] Storage/Realtime do not replace application authorization.

# Dependency Rules

## Allowed
- apps/web -> packages/validators
- apps/api -> packages/validators
- TasksService -> TaskRepository contract
- PrismaTaskRepository -> PrismaService

## Avoid / reject
- apps/web -> apps/api source imports
- shared package -> apps/web or apps/api
- service -> Fastify Reply/Request
- repository -> NestJS HTTP exceptions
- UI -> Prisma-generated model as public API contract

Every exception should be documented with a reason and revisit trigger.

# Package Boundary Review

## packages/validators
Earned because both web and API consume transport-neutral field rules. It must not become a dumping ground for server-only DTO semantics or UI code.

## Future package rule
Create a shared package only when:
1. There are at least two real consumers or a clear independent ownership boundary.
2. The package has a coherent responsibility.
3. Moving code there reduces coupling rather than hiding it.

Do not create generic `shared`, `common`, or `utils` packages without an explicit responsibility statement.

# TaskFlow Architecture Review Snapshot

This package contains review artifacts rather than a replacement application architecture.

Use it to:
- document the current system,
- identify actual pressure points,
- prioritize debt,
- record decisions with ADRs, and
- verify refactors without changing observable behavior accidentally.

The default stance is incremental improvement, not rewrite.

# Refactoring Backlog Template

| Priority | Area | Evidence | Risk | Proposed change | Verification |
|---|---|---|---|---|---|
| P0 | Example: tenant query | Cross-workspace test missing | Security | Add scoped repository test before any query refactor | Integration + E2E |
| P1 | Example: transaction workflow | Repeated multi-repository orchestration | Correctness | Evaluate explicit transaction boundary | Service + repository integration |
| P2 | Example: duplicated field rules | Same title limits in web/API | Drift | Move neutral field rule to validators package | Unit + form + API validation |
| P3 | Example: naming | Inconsistent helper names | Cosmetic | Rename when touching area | Typecheck/tests |

Priority is based on system pressure, not aesthetic preference.

# Source Basis

Phase 35 is an internal synthesis of the TaskFlow architecture established throughout Phases 00-34. It intentionally introduces no new framework dependency.

Review evidence should come from:
- the current repository,
- tests,
- runtime telemetry,
- deployment incidents,
- change frequency,
- security findings, and
- developer/operator friction.

If framework/provider behavior materially changes in the future, verify the relevant official documentation before altering architecture decisions based on it.

# API Review Example

Trace one endpoint end-to-end:

`PATCH /tasks/:id/status`

1. Controller: parse validated route/body and current user.
2. Authorization: verified identity and resource scope.
3. Service: status transition invariant and completedAt behavior.
4. Repository: scoped Task lookup/update query.
5. Prisma/PostgreSQL: persistence and constraints.
6. Exception filter: stable HTTP error contract.
7. Observability: requestId, timing, safe error classification.

If a responsibility appears in two incompatible owners, add it to the refactoring backlog.

# Frontend State Review Example

For `/tasks?status=DONE&page=2`:

- URL state: status=DONE, page=2
- TanStack Query: fetched page result
- React Hook Form: only create/edit draft
- Supabase Auth: session
- Local React state: menu/dialog/selection only where local
- Derived values: compute from current data; do not persist another copy

Reject any new store unless it solves a real state-ownership problem not already covered above.

Write-Host "TaskFlow Architecture Audit"
Write-Host "1. Search direct Prisma imports outside repository/infrastructure areas"
Write-Host "2. Search apps/web imports that reference apps/api"
Write-Host "3. Search repositories throwing HTTP exceptions"
Write-Host "4. Compare env variable names across local, CI, Docker, and deployment templates"
Write-Host "5. Run lint, typecheck, tests, production builds, and critical smoke tests"
Write-Host "This script is a checklist launcher, not an automatic architecture judge."

# Architecture Refactor Verification Matrix

| Refactor area | Minimum verification |
|---|---|
| Business policy extraction | Pure unit tests |
| Service/repository boundary | Service tests + repository integration tests |
| Tenant query restructure | Real PostgreSQL cross-workspace tests + HTTP E2E |
| Validation sharing | Browser form tests + API validation tests |
| Frontend state ownership | Component/query tests + critical Playwright flow |
| Authentication/authorization changes | 401/403/404 E2E matrix |
| Transaction changes | Integration tests with rollback/failure scenarios |
| Deployment/config refactor | CI build + staging smoke tests |
| Observability refactor | Synthetic error + requestId correlation check |