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: 22 etapów ([roadmapa](roadmap.md))
:material-locker: 1.5.52 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 · sprzęt przez agenta SmartConf (/v1, nie Modbus) · offline cache · OTA + nadzór przez Kiosk Helper.

    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 + panel-side upload + PowerShell OTA agent → Kiosk Helper
4 Workery (auto-OFFLINE / auto-EXPIRED), hardware abstraction, deposit flow, offline mode, mobile-parity API
5 Hardware Modbus + locker lifecycle hardening (Modbus martwy od etapu 9 → agent SmartConf)
6 ErgoFlow integration — sync, JIT user/Keycloak/RFID provisioning
7–9 Wydawanie/uzupełnianie + raporty · DynaBox · SmartConf (tryb serwisowy, discovery, komunikacja przez agenta)
10–18 Temrex UI · KioskKit + OTA · drzwi fizyczne/wirtualne · inwentaryzacja · audyt /v1 · Job API
19–22 1 skrytka = 1 funkcja · nazwy + drop Modbus · 2 tryby serwisowe · Kiosk Helper + generator instalatora

Pełny rozpis etapów 7–22 + co do zrobienia → Roadmapa.

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