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 |