Przejdź do treści

SmartBox

Self-hosted system paczkomatów

Pełna dokumentacja platformy: backend NestJS, panel operatora Next.js, kiosk Flutter na Windows desktop, własna infrastruktura w Docker Compose za Traefikiem. Zero managed cloud, zero zewnętrznego CI, zero rejestru — wszystko na jednej maszynie wirtualnej.

Architektura Repo na Gitea

:material-server: 1 VM produkcyjna
:material-package-variant: 6/8 etapów wdrożonych
:material-locker: v0.83 kiosk w produkcji

Skróty po projekcie

  • Backend

    NestJS 10 + Prisma + Postgres + RabbitMQ + Redis. Pełna lista endpointów, model danych, audit, workery.

    Backend reference

  • Panel operatora

    Next.js 15 App Router · server components · glass-morphism · next-intl PL/EN · server-paginated tabele.

    Panel reference

  • Kiosk

    Flutter Windows desktop · Modbus TCP · offline cache · OTA przez PowerShell agent.

    Kiosk reference

  • Infrastruktura

    Docker Compose · Traefik 3.5 · Postgres 16 · Keycloak 26 · Gitea 1.22 · Portainer · Dozzle.

    Infra runbook

Etapy projektu

Etap Zakres Status
0 Infrastruktura (Traefik, Postgres, Redis, RabbitMQ, Keycloak, Gitea, Portainer, Dozzle)
1 Backend core — users, machines, shipments, lockers, audit, dual auth (JWT + machine API key)
2 Panel operatora — login, dashboard, shipments, machines, users, audit, profile
3 Kiosk UI + OTA pipeline — Flutter Windows desktop + PowerShell OTA agent + panel-side upload
4 Workery (auto-OFFLINE / auto-EXPIRED), hardware abstraction, deposit flow, offline mode, mobile-parity API
5 Hardware Modbus + locker lifecycle hardening
6 ErgoFlow integration — sync, JIT user/Keycloak/RFID provisioning
7 Multi-machine sync, smart assignment, document/key-rental flows
8 Hardening — Prometheus + Grafana, OIDC code-flow, real notifications, Gitea Actions CI/CD

Dla kogo jest ta dokumentacja

Operatorzy

Sprawdź panel operatora — pełna mapa stron, role, flow nadawania i odbierania paczek.

Developerzy backendowi

Backend reference ma każdy endpoint, model Prisma i konwencję audytu. Live Swagger dostępny pod api.smartbox.ergoflow.app/docs.

Devops / SRE

Infrastruktura opisuje stos Compose, Traefik, certy Let's Encrypt i ścieżkę deploy tar | ssh. Kiosk runbook w infra/scripts/windows-kiosk/RUNTIME.md.

Integratorzy ErgoFlow

Etap 6 tłumaczy quirki upstreamu (clientTime, records envelope, double-encoded grupy), lifecycle firstSeenAt/deactivatedAt i model JIT-provisioningu.

Linki produkcyjne