# 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.