feat: establish auth listing and image vertical slices

Includes MFA-capable authentication, session and CSRF security, password recovery, listing lifecycle and ownership rules, inventory image metadata, local ImageStorage, migrations, tests, and implementation status documentation. Verification: npm test (62 passing) and integration suite (14 passing).
2026-09-08 17:32:03 -04:00
commit c728016dec
128 changed files with 9788 additions and 0 deletions
@@ -0,0 +1,87 @@
+# Architecture
+
+## Architectural style
+
+Modular monolith.
+
+Do not split domains into microservices unless a future architecture decision explicitly requires it.
+
+## Runtime topology
+
+```text
+Public Web
+  ↓ HTTPS
+Reverse Proxy
+  ↓
+Fastify API ───── PostgreSQL
+  │
+  ├────────────── Redis / BullMQ
+  │                    ↓
+  │                 Worker
+  │
+  └────────────── Image Storage
+```
+
+Docker Compose is the baseline deployment mechanism.
+
+## Applications
+
+### web
+Vue 3/Vite public and admin frontend.
+
+### api
+Fastify REST API. Owns authentication, authorization, domain use cases, persistence, and synchronous integrations.
+
+### worker
+Processes asynchronous jobs including bulk pricing, image processing, and large exports.
+
+## Modules
+
+API modules:
+- auth
+- users
+- sellers
+- products
+- inventory
+- listings
+- pricing
+- sales
+- images
+- search
+- settings
+- audit
+
+## Layering
+
+`Vue Component → Composable → API Service → HTTP → Fastify Route → Validation → Application Service → Domain Logic → Repository → PostgreSQL`
+
+## External boundaries
+
+Pricing providers implement `PricingProvider`.
+
+Image storage implements `ImageStorage`.
+
+Search is accessed through `SearchService`.
+
+Currency conversion is accessed through a currency/exchange-rate service.
+
+## Shared packages
+
+Only genuinely shared material belongs in `packages/*`:
+- API contracts
+- validation schemas
+- safe utilities
+
+Server-side domain logic stays on the server.
+
+## Search
+
+PostgreSQL-backed initially. Keep search behind an abstraction so OpenSearch/Elasticsearch can be introduced later without changing product-facing behavior.
+
+## Authentication
+
+Use server-side sessions with secure HttpOnly SameSite cookies. Authentication tokens must not be stored in localStorage.
+
+## Caching
+
+Use selective caching for stable/repeated data such as exchange rates, public metadata, and configuration. Avoid aggressive caching of mutations, financial calculations, auth state, and sale state.