Architecture Overview

Certexi is a production-grade, NFC-enabled customs workflow tracking system built with Next.js 14, TypeScript, and PostgreSQL. It provides real-time visibility into multi-stage customs operations with cryptographic verification and comprehensive audit trails.

System Architecture

Live Dashboard

Operational metrics at a glance — active transport units, warehouse utilization, daily throughput, and incident count. All metrics are derived from the event stream.

Technology Stack

Application Layers

Client Layer

The client layer supports multiple platforms through a single codebase:

• Web Browser — Full desktop experience with React 18 and server components
• Mobile PWA — Installable progressive web app with offline support and Web NFC
• NFC Scanner — Web NFC API integration for tag scanning (Android Chrome 89+)
• Desktop App — Electron wrapper for Windows, macOS, and Linux

Application Layer

Built on Next.js 14 with the App Router for hybrid rendering:

• Server Components for initial page loads and SEO
• API Routes for RESTful endpoints with Zod validation
• Middleware for authentication, rate limiting, and security headers
• Service Worker for offline caching and background sync

Business Logic Layer

Core services handle all business operations:

• Workflow Manager — Stage progression, validation rules, state transitions
• Auth Service — Nextcloud OAuth, JWT sessions, RBAC enforcement
• Offline Storage — IndexedDB event queueing, conflict resolution, sync coordination
• Rate Limiter — Per-user and per-IP limits with configurable windows

Data Access Layer

Drizzle ORM provides type-safe database access with 15 tables, 25 indexes, and version-controlled migrations. Core tables include operators, transport_units, events, and workflow_stage_history.

Data Flow

Event Creation

User Action (NFC Scan / Form Submit)
  → Client validation
  → API Request (POST /api/events)
  → Rate limit + Auth check
  → Business logic validation
  → Database transaction (event + transport unit + audit log)
  → External integrations (Flowhash proof, NFTC credential, Nextcloud evidence)
  → Response + UI update

Offline Sync

User Action (offline)
  → Queue in IndexedDB
  → Service Worker intercept
  → Network restored → Background sync
  → Process queued operations → Update server
  → Confirm sync → Remove from queue

External Integrations

Security Architecture

• Authentication: Nextcloud OAuth2 with JWT session tokens in httpOnly cookies
• Authorization: Role-based access control (operator, supervisor, admin) — see RBAC
• Data in Transit: HTTPS/TLS 1.3 enforced
• Data at Rest: PostgreSQL encryption, S3 server-side encryption
• Input Validation: Zod schemas on all API endpoints
• File Security: Type validation, size limits, ClamAV virus scanning

Module Organization

certexi/
├── app/                    # Next.js App Router
│   ├── (dashboard)/       # Dashboard routes
│   ├── scan/              # NFC scanning
│   ├── workflow/          # Stage workflows
│   └── api/               # 100+ API routes
├── components/            # React components (112+ widgets)
├── lib/                   # Business logic
│   ├── auth/              # RBAC, session management
│   ├── nfc/               # Web NFC API wrapper
│   ├── nextcloud/         # Nextcloud client
│   ├── whms/              # Warehouse management
│   ├── iot/               # CCTV, motion detection
│   └── offline/           # PWA offline storage
└── specs/                 # Specifications

Next Steps

• Map visualization system
• Warehouse management architecture
• Surveillance module
• Offline-first PWA design
• Deployment options