# zahoor-ishfaq/wasl-logistics-agent architecture

> Architecture diagram of the GitHub repository zahoor-ishfaq/wasl-logistics-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zahoor-ishfaq/wasl-logistics-agent
- Repository: https://github.com/zahoor-ishfaq/wasl-logistics-agent

## Overview

#### Purpose and Entry Points
Wasl is an agentic logistics control tower for Saudi import/customs operations. It provides grounded policy Q&A and human-approved shipment-exception investigations. Backend startup is FastAPI at `wasl-backend/app/main.py`; the React/Vite client starts from `wasl-frontend/src/main.jsx` and renders `wasl-frontend/src/App.jsx`.

#### API and Security Boundary
FastAPI routes expose answer, investigation, shipment, document, and authentication operations under `wasl-backend/app/api/`. Dependency/auth enforcement is centralized in `wasl-backend/app/api/deps.py` and `wasl-backend/app/api/security.py`. The frontend calls this API via `wasl-frontend/src/api.js`; it is a separate browser deployment boundary.

#### Grounded RAG Pipeline
Document ingestion turns policy PDFs/Markdown in `wasl-backend/data/documents/` into vectorized chunks. Runtime answer flow is `wasl-backend/app/rag/service.py` → `wasl-backend/app/rag/retriever.py` → `wasl-backend/app/rag/prompt.py`. Retrieval is a hard gate: absent relevant context, the service declines rather than invoking the LLM. Embeddings are local through `wasl-backend/app/services/embeddings.py`; vector persistence/access is behind `wasl-backend/app/services/vector_store.py`.

#### Investigation Agent Workflow
The LangGraph state machine in `wasl-backend/app/agent/graph.py` orchestrates investigation nodes in `wasl-backend/app/agent/nodes.py`, using state schemas from `wasl-backend/app/models/state.py`. It looks up shipment facts, evaluates policy/SLA context, branches on whether action is warranted, and produces a proposed response. The key safety boundary is structural: draft generation cannot send messages, and actionable work pauses for human approval.

#### Operational Tools and Domain Services
Agent capabilities are registered in `wasl-backend/app/tools/registry.py`: shipment lookup, ETA/SLA calculation, policy search, and message drafting are implemented under `wasl-backend/app/tools/`. Shipment persistence/business access is separated through `wasl-backend/app/services/shipment_service.py`, with ORM models in `wasl-backend/app/db_models.py` and API/domain schemas in `wasl-backend/app/models/`.

#### Models, LLM, and Storage
Claude is accessed through `wasl-backend/app/services/llm.py`; it is used for bounded judgment/generation rather than as the source of policy truth. PostgreSQL is configured through `wasl-backend/app/database.py`, evolved with Alembic migrations in `wasl-backend/alembic/versions/`, including pgvector document chunks. Configuration is environment-driven via `wasl-backend/app/config.py`.

#### Runtime and Deployment
The backend targets Python 3.11+, containerized by `wasl-backend/Dockerfile`; local composition is in `wasl-backend/docker-compose.yml`. The frontend is React/Vite, with Nginx packaging configuration at `wasl-frontend/nginx.conf`. AWS-oriented infrastructure, including RDS, migration resources, and frontend deployment, is defined in `wasl-backend/infra/main.tf`, `wasl-backend/infra/rds.tf`, and `wasl-backend/infra/migration.tf`.

Main entry points: [`wasl-backend/infra/main.tf`](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/infra/main.tf) (Containers and AWS infrastructure), [`wasl-backend/app/rag/service.py`](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/service.py) (Grounded answer service), [`wasl-backend/app/agent/graph.py`](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/graph.py) (Investigation workflow), [`wasl-backend/app/agent/nodes.py`](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/nodes.py) (Investigation nodes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_frontend_app["React control tower<br/>React/Vite UI<br/>[App.jsx]"]
  node_frontend_api["API client<br/>browser API layer<br/>[api.js]"]
  node_nginx["Nginx packaging<br/>frontend delivery<br/>[nginx.conf]"]
end

subgraph group_backend["Backend application"]
  node_api["FastAPI application<br/>API entry point<br/>[main.py]"]
  node_routes["API routes"]
  node_security{{"Auth and dependencies<br/>security boundary<br/>[deps.py]"}}
  node_rag_service["Grounded answer service<br/>RAG orchestrator<br/>[service.py]"]
  node_retriever["Policy retriever<br/>context gate<br/>[retriever.py]"]
  node_prompt["Grounded prompt builder<br/>RAG prompt layer<br/>[prompt.py]"]
  node_agent_graph{{"Investigation workflow<br/>LangGraph state machine<br/>[graph.py]"}}
  node_agent_nodes["Investigation nodes<br/>workflow actions<br/>[nodes.py]"]
  node_tools["Operational tool registry<br/>agent capabilities<br/>[registry.py]"]
  node_shipment_service["Shipment service<br/>domain persistence access"]
  node_embeddings["Local embeddings<br/>embedding service<br/>[embeddings.py]"]
end

subgraph group_data["Data and models"]
  node_agent_state["Investigation state<br/>state schemas<br/>[state.py]"]
  node_vector_store[("Vector store<br/>embedding persistence<br/>[vector_store.py]")]
  node_policy_documents["Policy documents<br/>PDF and Markdown corpus"]
  node_database[("PostgreSQL with pgvector<br/>operational and vector database<br/>[database.py]")]
end

subgraph group_platform["Runtime and infrastructure"]
  node_llm["Claude<br/>bounded generation model<br/>[llm.py]"]
  node_deployment["Containers and AWS infrastructure<br/>deployment platform<br/>[main.tf]"]
end

node_frontend_app -->|"uses"| node_frontend_api
node_frontend_api -->|"HTTPS API calls"| node_api
node_nginx -->|"serves"| node_frontend_app
node_api -->|"mounts"| node_routes
node_routes -->|"enforces"| node_security
node_routes -->|"answer requests"| node_rag_service
node_routes -->|"investigation requests"| node_agent_graph
node_routes -->|"shipment operations"| node_shipment_service
node_rag_service -->|"retrieves context"| node_retriever
node_retriever -->|"searches"| node_vector_store
node_rag_service -->|"builds grounded prompt"| node_prompt
node_prompt -->|"bounded generation"| node_llm
node_policy_documents -->|"ingested and chunked"| node_embeddings
node_embeddings -->|"writes vectors"| node_vector_store
node_vector_store -->|"persists in"| node_database
node_agent_graph -->|"uses state"| node_agent_state
node_agent_graph -->|"orchestrates"| node_agent_nodes
node_agent_nodes -->|"invokes"| node_tools
node_tools -->|"shipment lookup and SLA"| node_shipment_service
node_tools -->|"policy search"| node_retriever
node_agent_nodes -->|"proposes response"| node_llm
node_shipment_service -->|"reads and writes"| node_database
node_deployment -->|"provisions RDS and migrations"| node_database
node_deployment -->|"container deployment"| node_api
node_deployment -->|"frontend deployment"| node_nginx

click node_frontend_app "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/src/App.jsx"
click node_frontend_api "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/src/api.js"
click node_nginx "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/nginx.conf"
click node_api "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/main.py"
click node_security "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/api/deps.py"
click node_rag_service "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/service.py"
click node_retriever "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/retriever.py"
click node_prompt "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/prompt.py"
click node_agent_graph "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/graph.py"
click node_agent_nodes "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/nodes.py"
click node_agent_state "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/models/state.py"
click node_tools "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/tools/registry.py"
click node_shipment_service "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/shipment_service.py"
click node_vector_store "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/vector_store.py"
click node_embeddings "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/embeddings.py"
click node_database "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/database.py"
click node_llm "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/llm.py"
click node_deployment "https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/infra/main.tf"

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_frontend_app,node_frontend_api,node_nginx toneBlue
class node_api,node_routes,node_security,node_rag_service,node_retriever,node_prompt,node_agent_graph,node_agent_nodes,node_tools,node_shipment_service,node_embeddings toneAmber
class node_agent_state,node_vector_store,node_policy_documents,node_database toneMint
class node_llm,node_deployment toneRose
```

## Components

### Browser client

- [React control tower](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/src/App.jsx): React/Vite UI · `wasl-frontend/src/App.jsx`
- [API client](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/src/api.js): browser API layer · `wasl-frontend/src/api.js`
- [Nginx packaging](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-frontend/nginx.conf): frontend delivery · `wasl-frontend/nginx.conf`

### Backend application

- [FastAPI application](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/main.py): API entry point · `wasl-backend/app/main.py`
- **API routes**: answer, investigation, shipment and document endpoints
- [Auth and dependencies](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/api/deps.py): security boundary · Centralizes dependency and authentication enforcement. · `wasl-backend/app/api/deps.py`
- [Grounded answer service](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/service.py): RAG orchestrator · Declines when retrieval provides no relevant context. · `wasl-backend/app/rag/service.py`
- [Policy retriever](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/retriever.py): context gate · `wasl-backend/app/rag/retriever.py`
- [Grounded prompt builder](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/rag/prompt.py): RAG prompt layer · `wasl-backend/app/rag/prompt.py`
- [Investigation workflow](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/graph.py): LangGraph state machine · Pauses actionable work for human approval. · `wasl-backend/app/agent/graph.py`
- [Investigation nodes](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/agent/nodes.py): workflow actions · Looks up facts, evaluates policy and SLA, then proposes a response. · `wasl-backend/app/agent/nodes.py`
- [Operational tool registry](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/tools/registry.py): agent capabilities · Registers shipment lookup, ETA/SLA, policy search, and drafting. · `wasl-backend/app/tools/registry.py`
- [Shipment service](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/shipment_service.py): domain persistence access · `wasl-backend/app/services/shipment_service.py`
- [Local embeddings](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/embeddings.py): embedding service · `wasl-backend/app/services/embeddings.py`

### Data and models

- [Investigation state](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/models/state.py): state schemas · `wasl-backend/app/models/state.py`
- [Vector store](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/vector_store.py): embedding persistence · `wasl-backend/app/services/vector_store.py`
- **Policy documents**: PDF and Markdown corpus
- [PostgreSQL with pgvector](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/database.py): operational and vector database · `wasl-backend/app/database.py`

### Runtime and infrastructure

- [Claude](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/app/services/llm.py): bounded generation model · Used for judgment and generation, not policy truth. · `wasl-backend/app/services/llm.py`
- [Containers and AWS infrastructure](https://github.com/zahoor-ishfaq/wasl-logistics-agent/blob/main/wasl-backend/infra/main.tf): deployment platform · Defines backend container, RDS, migrations, and frontend deployment. · `wasl-backend/infra/main.tf`

## Connections

- React control tower → API client: uses
- API client → FastAPI application: HTTPS API calls
- Nginx packaging → React control tower: serves
- FastAPI application → API routes: mounts
- API routes → Auth and dependencies: enforces
- API routes → Grounded answer service: answer requests
- API routes → Investigation workflow: investigation requests
- API routes → Shipment service: shipment operations
- Grounded answer service → Policy retriever: retrieves context
- Policy retriever → Vector store: searches
- Grounded answer service → Grounded prompt builder: builds grounded prompt
- Grounded prompt builder → Claude: bounded generation
- Policy documents → Local embeddings: ingested and chunked
- Local embeddings → Vector store: writes vectors
- Vector store → PostgreSQL with pgvector: persists in
- Investigation workflow → Investigation state: uses state
- Investigation workflow → Investigation nodes: orchestrates
- Investigation nodes → Operational tool registry: invokes
- Operational tool registry → Shipment service: shipment lookup and SLA
- Operational tool registry → Policy retriever: policy search
- Investigation nodes → Claude: proposes response
- Shipment service → PostgreSQL with pgvector: reads and writes
- Containers and AWS infrastructure → PostgreSQL with pgvector: provisions RDS and migrations
- Containers and AWS infrastructure → FastAPI application: container deployment
- Containers and AWS infrastructure → Nginx packaging: frontend deployment