zahoor-ishfaq/wasl-logistics-agent

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.