# Architecture

Plock technical architecture, Kotlin/Ktor backend, React MFE frontend, PostgreSQL, Redis

# Tech Stack (CEO approved 2026-03-03)

# Tech Stack (CEO approved 2026-03-03)

## Decision Date
**CEO Approval:** 2026-03-03
**Supersedes:** Express + TypeScript backend, monolithic Next.js frontend

---

## Backend

| Component | Choice | Rationale |
|-----------|--------|-----------|
| Language | Kotlin | Type-safe, JVM performance, JetBrains ecosystem |
| Framework | Ktor | Coroutine-based async, lightweight, idiomatic Kotlin |
| Database | PostgreSQL 16 | Rock-solid relational DB, JSONB for flexible fields |
| ORM | Kotlin Exposed | Type-safe SQL DSL, no annotation magic |
| Build tool | Gradle (Kotlin DSL) | Standard for Kotlin/JVM projects |
| Testing | Kotest + Testcontainers | BDD-style tests, real DB for integration tests |
| Auth | JWT (24h expiry) + refresh tokens | Standard stateless auth |
| Queue | Kotlin coroutines + Redis | Async jobs: label generation, carrier calls |

---

## Frontend — Micro-Frontend Architecture

| Component | Choice | Rationale |
|-----------|--------|-----------|
| Framework | React 19 + TypeScript | Stable, large ecosystem |
| Bundler | Vite + Module Federation | MFE-ready, fast HMR |
| Architecture | Micro-Frontend (MFE) | Each feature independently deployable |
| Shared UI | Tailwind CSS 4 + shadcn/ui | Design tokens in packages/ui/ |
| State | Zustand per MFE | Lightweight, no global store coupling |

### MFE Structure

| MFE | Responsibility | Deploy |
|-----|---------------|--------|
| shell | Layout, routing, auth, navigation | Always |
| mfe-inventory | Inventory management, bin locations, cycle counts | Independent |
| mfe-orders | Order management, inbound/outbound | Independent |
| mfe-picking | Picking workflows, wave management | Independent |
| mfe-settings | User management, integrations, config | Independent |
| mfe-ai | Plock AI Chat, analytics, dashboards | Independent |

Each MFE is **independently deployable** — a change to mfe-picking does not require redeploying the shell or other MFEs.

---

## AI / ML Layer

| Component | Choice | Use Case |
|-----------|--------|----------|
| LLM | Claude API (claude-sonnet-4-5) | Plock AI Chat — Swedish NL queries |
| ML framework | Python microservice | Isolation from JVM, flexible ML tooling |
| Route optimisation | OR-Tools (Google) | Smart Picking — VRP/TSP solver |
| Anomaly detection | scikit-learn | Z-score + isolation forest |
| Forecasting (Phase 2) | XGBoost / Prophet | Demand forecasting |

---

## Infrastructure

| Component | Choice |
|-----------|--------|
| Monorepo | Turborepo (frontend MFEs) + Gradle (Kotlin backend) |
| Mobile (Phase 2) | React Native — scanner + picking app |
| Cache | Redis |
| Testing (frontend) | Vitest + Playwright |
| CI/CD | GitHub Actions |
| Containers | Docker + Docker Compose (local dev) |

---

## Architecture Decision Records

### ADR-001: Kotlin over TypeScript for backend (2026-03-03)
Context: Previous design used Express + TypeScript. Decision to move to Kotlin + Ktor.
Rationale: JVM performance for WMS workloads, stronger type safety with Exposed ORM, coroutine-based concurrency fits async warehouse operations (carrier calls, label generation).
Status: Accepted by CEO 2026-03-03.

### ADR-002: Micro-Frontend over monolithic Next.js (2026-03-03)
Context: WMS has distinct feature domains that evolve at different rates (picking vs AI vs integrations).
Rationale: Independent deployment reduces risk, enables feature teams to work in parallel, allows phased feature releases.
Trade-off: Higher initial complexity, but pays off at scale.
Status: Accepted by CEO 2026-03-03.

# Project Structure

# Project Structure

## Monorepo Layout

The Plock monorepo uses Turborepo for frontend orchestration and Gradle for the Kotlin backend.

**Root folders:**

- **backend/** — Kotlin/Ktor backend (Gradle). Namespace: no.alai.plock
  - Application.kt — Ktor entry point
  - plugins/ — Routing, serialization, auth, CORS
  - routes/ — API routes by domain (auth, inventory, orders, picking, carriers, ai)
  - models/ — Data classes + Exposed table definitions
  - services/ — Business logic
  - integrations/ — Fortnox, PostNord, DHL, Instabee

- **frontend/** — Micro-Frontend apps (Vite + Module Federation)
  - shell/ — Shell MFE: layout, nav, auth, routing (always deployed)
  - mfe-inventory/ — Inventory management (independently deployable)
  - mfe-orders/ — Order management (independently deployable)
  - mfe-picking/ — Picking + wave management (independently deployable)
  - mfe-settings/ — Settings + users (independently deployable)
  - mfe-ai/ — AI Chat + analytics (independently deployable)

- **packages/** — Shared libraries
  - ui/ — @plock/ui: shadcn/ui base + Plock custom components, Tailwind CSS 4 design tokens
  - types/ — @plock/types: shared TypeScript types (API contracts)
  - utils/ — @plock/utils: shared utilities

- **docs/** — All documentation (mirrors BookStack)
- **brand/** — Brand assets (colours, logo, typography)
- **design/** — Figma exports, wireframes (via frontend-design skill — ZAKON #3)
- **infrastructure/** — Docker Compose, CI/CD, K8s manifests
- **legal/** — Swedish regulatory compliance (GDPR, moms, Intrastat)
- **marketing/** — GTM materials

---

## Key Conventions

| Convention | Detail |
|------------|--------|
| Package names | @plock/ui, @plock/types, @plock/utils |
| Backend namespace | no.alai.plock |
| Environment secrets | .env.local — never committed to git |
| API base URL | api.plock.se (production), localhost:8080 (local) |
| Frontend URL | plock.se (shell), MFEs on sub-paths or CDN |
| Test coverage target | 80%+ for services layer |
| DB migrations | Exposed schema + migration scripts in backend/src/main/resources/migrations/ |

---

## Root Config Files

| File | Purpose |
|------|---------|
| docker-compose.yml | Local dev services: PostgreSQL, Redis, backend, shell |
| turbo.json | Turborepo pipeline: build, dev, test, lint |
| build.gradle.kts | Kotlin backend build config |
| CLAUDE.md | Project handbook (AI director instructions) |
| PIPELINE.md | 8-gate pipeline tracker |