# ackzerman/assignment architecture

> Architecture diagram of the GitHub repository ackzerman/assignment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ackzerman/assignment
- Repository: https://github.com/ackzerman/assignment

## Overview

The Parcel Routing System turns parcel data into explainable department and approval decisions. Operators can route one parcel synchronously or upload a batch, which is validated, queued, processed in chunks, and made available through progress polling and paginated results. The React interface presents both workflows. Redis holds temporary batch state and BullMQ work; health checks and metrics expose operational status. The graph follows documented and sampled wiring; unsampled frontend and infrastructure details are represented only where the README supports them.

Main entry points: [`backend/src/app.js`](https://github.com/ackzerman/assignment/blob/main/backend/src/app.js) (Express application), [`backend/src/api/routes/batchRoutes.js`](https://github.com/ackzerman/assignment/blob/main/backend/src/api/routes/batchRoutes.js) (Batch endpoints), [`backend/src/infrastructure/worker.js`](https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/worker.js) (Batch worker), [`frontend/src/App.jsx`](https://github.com/ackzerman/assignment/blob/main/frontend/src/App.jsx) (Application shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Operator interface"]
  node_app_ui["Application shell<br/>[App.jsx]"]
  node_parcel_form["Single parcel form<br/>[ParcelForm.jsx]"]
  node_batch_upload["Batch upload<br/>[BatchUpload.jsx]"]
  node_routing_result["Routing result<br/>[RoutingResult.jsx]"]
  node_batch_results["Batch results<br/>[BatchResults.jsx]"]
  node_frontend_api["API client<br/>[api.js]"]
end

subgraph group_api["HTTP API"]
  node_express_app["Express application<br/>[app.js]"]
  node_parcel_routes["Parcel endpoints<br/>[parcelRoutes.js]"]
  node_batch_routes["Batch endpoints<br/>[batchRoutes.js]"]
  node_middleware_security["Security middleware<br/>[security.js]"]
  node_middleware_logging["Request logging<br/>[requestLogger.js]"]
  node_error_handler["Error handling<br/>[errorHandler.js]"]
end

subgraph group_domain["Routing domain"]
  node_validation["Parcel validation<br/>[validation.js]"]
  node_batch_validation["Batch validation<br/>[batchProcessor.js]"]
  node_routing_engine["Routing engine<br/>[routingEngine.js]"]
  node_rules["Routing rules<br/>[rules.js]"]
end

subgraph group_batch["Batch processing"]
  node_queue["BullMQ queue<br/>[queue.js]"]
  node_worker["Batch worker<br/>[worker.js]"]
  node_batch_store[("Temporary batch state<br/>[batchStore.js]")]
  node_redis_client["Redis client<br/>[redis.js]"]
end

subgraph group_ops["Operations"]
  node_metrics[("Metrics<br/>[metrics.js]")]
  node_anomaly["Anomaly detection<br/>[anomalyDetector.js]"]
  node_logger["Structured logger<br/>[logger.js]"]
end

node_operator(("Parcel operator"))
node_redis[("Redis")]

node_operator -->|"uses"| node_app_ui
node_app_ui -->|"renders"| node_parcel_form
node_app_ui -->|"renders"| node_batch_upload
node_app_ui -->|"shows"| node_routing_result
node_app_ui -->|"shows"| node_batch_results
node_parcel_form -->|"submits parcel"| node_frontend_api
node_batch_upload -->|"submits batch"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_express_app
node_express_app -->|"dispatches"| node_parcel_routes
node_express_app -->|"dispatches"| node_batch_routes
node_express_app -->|"applies"| node_middleware_security
node_express_app -->|"applies"| node_middleware_logging
node_express_app -->|"handles errors"| node_error_handler
node_parcel_routes -->|"validates"| node_validation
node_parcel_routes -->|"routes parcel"| node_routing_engine
node_parcel_routes -->|"records outcomes"| node_metrics
node_parcel_routes -->|"logs outcomes"| node_logger
node_routing_engine -->|"evaluates"| node_rules
node_batch_routes -->|"validates batch"| node_batch_validation
node_batch_routes -->|"checks Redis"| node_redis_client
node_batch_routes -->|"creates and reads state"| node_batch_store
node_batch_routes -->|"enqueues batch"| node_queue
node_batch_routes -->|"updates queue depth"| node_metrics
node_queue -->|"uses connection"| node_redis_client
node_batch_store -->|"uses connection"| node_redis_client
node_redis_client -->|"connects"| node_redis
node_queue -->|"dispatches jobs"| node_worker
node_worker -->|"loads and checkpoints"| node_batch_store
node_worker -->|"validates parcels"| node_validation
node_worker -->|"routes parcels"| node_routing_engine
node_worker -->|"records jobs"| node_metrics
node_worker -->|"logs errors"| node_logger
node_express_app -->|"serves metrics"| node_metrics
node_express_app -->|"checks queue health"| node_queue
node_express_app -->|"checks readiness"| node_redis_client
node_express_app -->|"checks alerts"| node_anomaly
node_error_handler -->|"records errors"| node_metrics
node_error_handler -->|"logs errors"| node_logger

click node_app_ui "https://github.com/ackzerman/assignment/blob/main/frontend/src/App.jsx"
click node_parcel_form "https://github.com/ackzerman/assignment/blob/main/frontend/src/components/ParcelForm.jsx"
click node_batch_upload "https://github.com/ackzerman/assignment/blob/main/frontend/src/components/BatchUpload.jsx"
click node_routing_result "https://github.com/ackzerman/assignment/blob/main/frontend/src/components/RoutingResult.jsx"
click node_batch_results "https://github.com/ackzerman/assignment/blob/main/frontend/src/components/BatchResults.jsx"
click node_frontend_api "https://github.com/ackzerman/assignment/blob/main/frontend/src/api.js"
click node_express_app "https://github.com/ackzerman/assignment/blob/main/backend/src/app.js"
click node_parcel_routes "https://github.com/ackzerman/assignment/blob/main/backend/src/api/routes/parcelRoutes.js"
click node_batch_routes "https://github.com/ackzerman/assignment/blob/main/backend/src/api/routes/batchRoutes.js"
click node_validation "https://github.com/ackzerman/assignment/blob/main/backend/src/domain/validation.js"
click node_batch_validation "https://github.com/ackzerman/assignment/blob/main/backend/src/domain/batchProcessor.js"
click node_routing_engine "https://github.com/ackzerman/assignment/blob/main/backend/src/domain/routingEngine.js"
click node_rules "https://github.com/ackzerman/assignment/blob/main/backend/src/domain/rules.js"
click node_queue "https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/queue.js"
click node_worker "https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/worker.js"
click node_batch_store "https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/batchStore.js"
click node_redis_client "https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/redis.js"
click node_middleware_security "https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/security.js"
click node_middleware_logging "https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/requestLogger.js"
click node_error_handler "https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/errorHandler.js"
click node_metrics "https://github.com/ackzerman/assignment/blob/main/backend/src/observability/metrics.js"
click node_anomaly "https://github.com/ackzerman/assignment/blob/main/backend/src/observability/anomalyDetector.js"
click node_logger "https://github.com/ackzerman/assignment/blob/main/backend/src/observability/logger.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_ui,node_parcel_form,node_batch_upload,node_routing_result,node_batch_results,node_frontend_api toneBlue
class node_express_app,node_parcel_routes,node_batch_routes,node_middleware_security,node_middleware_logging,node_error_handler,node_redis toneAmber
class node_validation,node_batch_validation,node_routing_engine,node_rules toneMint
class node_queue,node_worker,node_batch_store,node_redis_client toneRose
class node_metrics,node_anomaly,node_logger,node_operator toneIndigo
```

## Components

### Operator interface

- [Application shell](https://github.com/ackzerman/assignment/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Single parcel form](https://github.com/ackzerman/assignment/blob/main/frontend/src/components/ParcelForm.jsx): `frontend/src/components/ParcelForm.jsx`
- [Batch upload](https://github.com/ackzerman/assignment/blob/main/frontend/src/components/BatchUpload.jsx): `frontend/src/components/BatchUpload.jsx`
- [Routing result](https://github.com/ackzerman/assignment/blob/main/frontend/src/components/RoutingResult.jsx): `frontend/src/components/RoutingResult.jsx`
- [Batch results](https://github.com/ackzerman/assignment/blob/main/frontend/src/components/BatchResults.jsx): `frontend/src/components/BatchResults.jsx`
- [API client](https://github.com/ackzerman/assignment/blob/main/frontend/src/api.js): `frontend/src/api.js`

### HTTP API

- [Express application](https://github.com/ackzerman/assignment/blob/main/backend/src/app.js): `backend/src/app.js`
- [Parcel endpoints](https://github.com/ackzerman/assignment/blob/main/backend/src/api/routes/parcelRoutes.js): `backend/src/api/routes/parcelRoutes.js`
- [Batch endpoints](https://github.com/ackzerman/assignment/blob/main/backend/src/api/routes/batchRoutes.js): `backend/src/api/routes/batchRoutes.js`
- [Security middleware](https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/security.js): `backend/src/api/middleware/security.js`
- [Request logging](https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/requestLogger.js): `backend/src/api/middleware/requestLogger.js`
- [Error handling](https://github.com/ackzerman/assignment/blob/main/backend/src/api/middleware/errorHandler.js): `backend/src/api/middleware/errorHandler.js`

### Routing domain

- [Parcel validation](https://github.com/ackzerman/assignment/blob/main/backend/src/domain/validation.js): `backend/src/domain/validation.js`
- [Batch validation](https://github.com/ackzerman/assignment/blob/main/backend/src/domain/batchProcessor.js): `backend/src/domain/batchProcessor.js`
- [Routing engine](https://github.com/ackzerman/assignment/blob/main/backend/src/domain/routingEngine.js): `backend/src/domain/routingEngine.js`
- [Routing rules](https://github.com/ackzerman/assignment/blob/main/backend/src/domain/rules.js): `backend/src/domain/rules.js`

### Batch processing

- [BullMQ queue](https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/queue.js): `backend/src/infrastructure/queue.js`
- [Batch worker](https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/worker.js): `backend/src/infrastructure/worker.js`
- [Temporary batch state](https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/batchStore.js): `backend/src/infrastructure/batchStore.js`
- [Redis client](https://github.com/ackzerman/assignment/blob/main/backend/src/infrastructure/redis.js): `backend/src/infrastructure/redis.js`

### Operations

- [Metrics](https://github.com/ackzerman/assignment/blob/main/backend/src/observability/metrics.js): `backend/src/observability/metrics.js`
- [Anomaly detection](https://github.com/ackzerman/assignment/blob/main/backend/src/observability/anomalyDetector.js): `backend/src/observability/anomalyDetector.js`
- [Structured logger](https://github.com/ackzerman/assignment/blob/main/backend/src/observability/logger.js): `backend/src/observability/logger.js`

### Other components

- **Parcel operator**
- **Redis**

## Connections

- Parcel operator → Application shell: uses
- Application shell → Single parcel form: renders
- Application shell → Batch upload: renders
- Application shell → Routing result: shows
- Application shell → Batch results: shows
- Single parcel form → API client: submits parcel
- Batch upload → API client: submits batch
- API client → Express application: HTTP requests
- Express application → Parcel endpoints: dispatches
- Express application → Batch endpoints: dispatches
- Express application → Security middleware: applies
- Express application → Request logging: applies
- Express application → Error handling: handles errors
- Parcel endpoints → Parcel validation: validates
- Parcel endpoints → Routing engine: routes parcel
- Parcel endpoints → Metrics: records outcomes
- Parcel endpoints → Structured logger: logs outcomes
- Routing engine → Routing rules: evaluates
- Batch endpoints → Batch validation: validates batch
- Batch endpoints → Redis client: checks Redis
- Batch endpoints → Temporary batch state: creates and reads state
- Batch endpoints → BullMQ queue: enqueues batch
- Batch endpoints → Metrics: updates queue depth
- BullMQ queue → Redis client: uses connection
- Temporary batch state → Redis client: uses connection
- Redis client → Redis: connects
- BullMQ queue → Batch worker: dispatches jobs
- Batch worker → Temporary batch state: loads and checkpoints
- Batch worker → Parcel validation: validates parcels
- Batch worker → Routing engine: routes parcels
- Batch worker → Metrics: records jobs
- Batch worker → Structured logger: logs errors
- Express application → Metrics: serves metrics
- Express application → BullMQ queue: checks queue health
- Express application → Redis client: checks readiness
- Express application → Anomaly detection: checks alerts
- Error handling → Metrics: records errors
- Error handling → Structured logger: logs errors