beaus-tolling

Architecture

Architectural Thesis

Beaus is designed as a modular tolling operations platform where business domains can evolve independently, be sold independently, and integrate cleanly with roadside, identity, payment, DMV, reporting, and agency ecosystems.

The architecture must support three goals at the same time:

• commercial modularity
• operational reliability
• long-term integration freedom

Platform Shape

flowchart LR
  subgraph UIs
    CRM["CRM UI"]
    CASE["Case Management UI"]
    FUL["Fulfillment UI"]
    CFG["Configuration UI"]
    REP["Report UI"]
    ONLINE["Online UI"]
  end

  subgraph Backoffice Services
    SSO["sso-service"]
    CORE["core-service"]
    ACC["account-service"]
    VEH["vehicle-service"]
    TRIP["trip-service"]
    CASESVC["case-service"]
    PAY["payment-service"]
    NOTI["notification-service"]
    DMV["dmv-service"]
    OOS["oos-service"]
    BATCH["batch-service"]
    REPORT["report-service"]
  end

  subgraph Platform
    KAFKA["Kafka"]
    REDIS["Redis"]
    PG["PostgreSQL per service"]
    S3["Object storage"]
    CONTRACTS["OpenAPI / AsyncAPI contracts"]
  end

  subgraph Roadside Repo
    LANE["Lane event ingest"]
    DEVICE["Device management"]
    IMG["Image evidence"]
  end

  CRM --> SSO
  CASE --> SSO
  FUL --> SSO
  CFG --> SSO
  REP --> SSO
  ONLINE --> SSO

  CRM --> ACC
  CRM --> VEH
  CRM --> TRIP
  CRM --> PAY
  CASE --> CASESVC
  CASE --> TRIP
  CASE --> PAY
  FUL --> CORE
  REP --> REPORT
  CFG --> CORE

  ACC --- PG
  VEH --- PG
  TRIP --- PG
  CASESVC --- PG
  PAY --- PG
  REPORT --- PG
  SSO --- REDIS

  ACC --> KAFKA
  VEH --> KAFKA
  TRIP --> KAFKA
  CASESVC --> KAFKA
  PAY --> KAFKA
  NOTI --> KAFKA
  LANE --> KAFKA
  DEVICE --> KAFKA
  IMG --> S3
  KAFKA --- CONTRACTS

Architectural Rules

1. Each service owns its own persistence.
2. No direct service-to-service database reads.
3. Shared models must come from contracts, not hidden code coupling.
4. Cross-domain state changes should prefer event propagation over synchronous dependency chains.
5. Reporting must use projections and read models, not reach into live transactional tables owned by other services.

Service Portfolio

core-service

System-wide reference and governance capabilities:

• plazas
• fee schedules
• program configuration
• master data
• feature flags

account-service

Customer account lifecycle:

• account profile
• balance and status
• communication preferences
• account-level operational context

vehicle-service

Vehicle and tag ownership relationships:

• vehicles
• plates
• transponders
• assignments

trip-service

Trip ledger and toll event processing:

• normalized trip records
• posting outcomes
• evidence linkage
• reconciliation projections

case-service

Operational exceptions and workflows:

• disputes
• refunds
• escalations
• manual review
• SLA orchestration

payment-service

Money movement orchestration:

• payment capture records
• refund flow support
• settlement state
• payment method integration

notification-service

Customer communication orchestration:

• email
• SMS
• letters
• delivery preference routing

dmv-service

External registration and vehicle owner enrichment.

oos-service

Out-of-state and external agency integration workflows.

batch-service

Scheduled and heavy operational workloads:

• close-of-day jobs
• recalculation
• bulk exports
• retention tasks

report-service

Read-optimized analytics and operational reporting.

sso-service

Identity gateway, session handling, and application launch control.

Roadside Relationship

Roadside remains in a separate repository because lane capture and device operations have a different change profile, runtime posture, and delivery lifecycle.

The connection to backoffice is contract-driven:

• trip capture events
• evidence and image linkage
• device health and roadside operational telemetry

Suggested Technical Baseline

• Java 21
• Spring Boot
• PostgreSQL
• Kafka
• Redis
• Docker and Kubernetes
• OpenTelemetry
• object storage for evidence and exports

Why This Architecture Sells

This architecture is commercially useful because it lets Beaus say three credible things to buyers:

• you can start with a focused scope
• you will not be trapped in a monolith
• the platform is designed to survive real-world tolling integrations