# ArchiTools — Architecture Quick Reference

## Data Flow

```
Browser → Traefik (tools.beletage.ro) → Next.js :3000
                                          ├── App Router (pages)
                                          ├── API Routes (/api/*)
                                          │     ├── Prisma → PostgreSQL + PostGIS
                                          │     ├── MinIO (file storage)
                                          │     ├── eTerra ANCPI (external GIS API)
                                          │     └── Brevo SMTP (email notifications)
                                          └── Auth: NextAuth → Authentik OIDC
```

## Module Dependencies

```
registratura ←→ address-book    (bidirectional: contacts + reverse lookup)
parcel-sync  →  geoportal       (map components reuse)
geoportal    →  PostGIS          (spatial queries, vector tiles)
parcel-sync  →  eTerra API       (external: ANCPI cadastral data)
parcel-sync  →  ePay API         (external: ANCPI CF extract ordering)
parcel-sync  →  MinIO            (CF extract PDF storage)
notifications → registratura     (deadline digest data)
all modules  → core/storage      (KeyValueStore via Prisma)
all modules  → core/auth         (Authentik SSO session)
```

## Critical API Routes (Write Operations)

| Route                              | Method | What it does                        | Auth      |
| ---------------------------------- | ------ | ----------------------------------- | --------- |
| `/api/storage`                     | PUT/DELETE | KeyValueStore CRUD               | Middleware |
| `/api/registratura`                | POST/PUT/DELETE | Registry entries + audit      | Middleware + Bearer |
| `/api/registratura/reserved`       | POST   | Reserve future registry slots       | Middleware |
| `/api/registratura/debug-sequences`| POST/PATCH | Reset sequence counters        | Admin only |
| `/api/vault`                       | PUT/DELETE | Encrypted vault entries          | Middleware |
| `/api/address-book`                | PUT/DELETE | Contact CRUD                     | Middleware + Bearer |
| `/api/eterra/sync-background`      | POST   | Start GIS sync job                  | Middleware |
| `/api/eterra/uats`                 | POST/PATCH | UAT management + county refresh | Middleware |
| `/api/ancpi/order`                 | POST   | ePay CF extract order               | Middleware |
| `/api/notifications/digest`        | POST   | Trigger email digest                | Bearer    |
| `/api/notifications/preferences`   | PUT    | User notification prefs             | Middleware |
| `/api/compress-pdf/*`              | POST   | PDF compression/unlock              | requireAuth |

## Storage Architecture

```
KeyValueStore (Prisma)          GisFeature (PostGIS)           MinIO
├── namespace: module-id        ├── layerId + objectId         ├── bucket: tools
├── key: entity UUID            ├── geometry (GeoJSON)         ├── bucket: ancpi-cf
└── value: JSON blob            ├── enrichment (JSONB)         └── PDF files
                                └── geom (native PostGIS)
```

## Auth Flow

```
User → /auth/signin → Authentik OIDC → callback → NextAuth session
  ├── Middleware: checks JWT token, redirects if unauthenticated
  ├── Portal-only users: env PORTAL_ONLY_USERS → redirected to /portal
  └── API routes excluded from middleware: use requireAuth() or Bearer token
```

## Environment Variables (Critical)

| Var                    | Required | Used by                    |
| ---------------------- | -------- | -------------------------- |
| `DATABASE_URL`         | Yes      | Prisma                     |
| `NEXTAUTH_SECRET`      | Yes      | NextAuth JWT               |
| `NEXTAUTH_URL`         | Yes      | Auth redirects             |
| `ENCRYPTION_SECRET`    | Yes      | Password Vault AES-256     |
| `STIRLING_PDF_URL`     | Yes      | PDF compression/unlock     |
| `STIRLING_PDF_API_KEY` | Yes      | Stirling PDF auth          |
| `NOTIFICATION_CRON_SECRET` | Yes  | Digest endpoint Bearer     |
| `MINIO_*`              | Yes      | MinIO connection           |
| `ANCPI_*`              | For ePay | ePay CF ordering           |
| `ILOVEPDF_PUBLIC_KEY`  | Optional | Cloud PDF compression      |
| `PORTAL_ONLY_USERS`    | Optional | Comma-separated usernames  |