# nithila-randil/importease-backend architecture

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

- Interactive diagram: https://gitdiagram.com/nithila-randil/importease-backend
- Repository: https://github.com/nithila-randil/importease-backend

## Overview

ImportEase is a backend API for importers and clearing agents managing Sri Lankan import clearance. The main workflow is shipment creation, tendering and bidding, agent assignment, clearance-stage updates, and shipment documents and notifications. Supporting capabilities include HS-code search and duty estimates, agency administration, agent verification, ratings, and messaging. The excerpts show Firestore-backed route behavior, Firebase token checks, and external search/rate services; several route modules are represented from the source index, so their internal behavior is not inferred.

Main entry points: [`main.py`](https://github.com/nithila-randil/importease-backend/blob/main/main.py) (FastAPI application), [`routes/hscode_routes.py`](https://github.com/nithila-randil/importease-backend/blob/main/routes/hscode_routes.py) (HS-code services), [`routes/notification_routes.py`](https://github.com/nithila-randil/importease-backend/blob/main/routes/notification_routes.py) (Notifications), [`routes/auth_routes.py`](https://github.com/nithila-randil/importease-backend/blob/main/routes/auth_routes.py) (Accounts and profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Accounts and profiles<br/>[auth_routes.py]"]
  node_access["Token and role checks<br/>[dependencies.py]"]
  node_firebase["Firestore client<br/>[firebase_setup.py]"]
  node_firestore[("Firestore database")]
  node_firebaseauth["Firebase Authentication"]
end

subgraph group_market["Clearance marketplace"]
  node_agencies["Agency directory<br/>[agency_routes.py]"]
  node_shipments["Shipment tracking<br/>[shipment_routes.py]"]
  node_tenders["Tender and bids<br/>[tender_routes.py]"]
  node_documents["Shipment documents<br/>[document_routes.py]"]
  node_notifications["Notifications"]
  node_uploads[("Uploaded files<br/>[document_routes.py]")]
end

subgraph group_trade["Trade tools"]
  node_hscode["HS-code services<br/>[hscode_routes.py]"]
  node_duty["Duty calculation<br/>[duty_calculator.py]"]
  node_pinecone["Pinecone search"]
  node_exchange["Exchange-rate service"]
  node_hscodeimport["HS-code import"]
end

subgraph group_operations["Operations and oversight"]
  node_ratings["Agent ratings"]
  node_verification["Agent verification"]
  node_adminroutes["Administration<br/>[admin_routes.py]"]
  node_messages["Messages<br/>[message_routes.py]"]
end

node_users(("Importer or agent"))
node_admin(("Platform admin"))

node_users -->|"calls API"| node_api
node_admin -->|"calls API"| node_api
node_api -->|"routes to"| node_auth
node_api -->|"routes to"| node_agencies
node_api -->|"routes to"| node_hscode
node_api -->|"routes to"| node_shipments
node_api -->|"routes to"| node_tenders
node_api -->|"routes to"| node_documents
node_api -->|"routes to"| node_notifications
node_api -->|"routes to"| node_ratings
node_api -->|"routes to"| node_adminroutes
node_api -->|"routes to"| node_verification
node_api -->|"routes to"| node_messages
node_auth -->|"creates users"| node_firebaseauth
node_access -->|"verifies tokens"| node_firebaseauth
node_auth -->|"reads and writes"| node_firestore
node_agencies -->|"reads and writes"| node_firestore
node_shipments -->|"reads and writes"| node_firestore
node_tenders -->|"reads and writes"| node_firestore
node_documents -->|"stores metadata"| node_firestore
node_documents -->|"writes files"| node_uploads
node_hscode -->|"reads details"| node_firestore
node_hscode -->|"searches codes"| node_pinecone
node_hscode -->|"fetches rates"| node_exchange
node_hscode -.->|"calculates duties"| node_duty
node_shipments -->|"creates alerts"| node_notifications
node_tenders -->|"creates alerts"| node_notifications
node_notifications -->|"reads and writes"| node_firestore
node_ratings -.->|"uses database"| node_firestore
node_verification -.->|"uses database"| node_firestore
node_adminroutes -->|"reads and writes"| node_firestore
node_messages -.->|"uses database"| node_firestore
node_hscodeimport -.->|"imports catalogue"| node_firestore
node_firebase -->|"initializes client"| node_firestore

click node_api "https://github.com/nithila-randil/importease-backend/blob/main/main.py"
click node_auth "https://github.com/nithila-randil/importease-backend/blob/main/routes/auth_routes.py"
click node_access "https://github.com/nithila-randil/importease-backend/blob/main/dependencies.py"
click node_firebase "https://github.com/nithila-randil/importease-backend/blob/main/firebase_setup.py"
click node_agencies "https://github.com/nithila-randil/importease-backend/blob/main/routes/agency_routes.py"
click node_shipments "https://github.com/nithila-randil/importease-backend/blob/main/routes/shipment_routes.py"
click node_tenders "https://github.com/nithila-randil/importease-backend/blob/main/routes/tender_routes.py"
click node_documents "https://github.com/nithila-randil/importease-backend/blob/main/routes/document_routes.py"
click node_notifications "https://github.com/nithila-randil/importease-backend/blob/main/routes/notification_routes.py"
click node_hscode "https://github.com/nithila-randil/importease-backend/blob/main/routes/hscode_routes.py"
click node_duty "https://github.com/nithila-randil/importease-backend/blob/main/services/duty_calculator.py"
click node_ratings "https://github.com/nithila-randil/importease-backend/blob/main/routes/agent_rating_routes.py"
click node_verification "https://github.com/nithila-randil/importease-backend/blob/main/routes/agent_verification_routes.py"
click node_adminroutes "https://github.com/nithila-randil/importease-backend/blob/main/routes/admin_routes.py"
click node_messages "https://github.com/nithila-randil/importease-backend/blob/main/routes/message_routes.py"
click node_hscodeimport "https://github.com/nithila-randil/importease-backend/blob/main/scripts/import_hscodes_from_pdf.py"
click node_uploads "https://github.com/nithila-randil/importease-backend/blob/main/routes/document_routes.py"

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_api,node_auth,node_access,node_firebase,node_firestore,node_firebaseauth toneBlue
class node_agencies,node_shipments,node_tenders,node_documents,node_notifications,node_uploads toneAmber
class node_hscode,node_duty,node_pinecone,node_exchange,node_hscodeimport toneMint
class node_ratings,node_verification,node_adminroutes,node_messages toneRose
class node_users,node_admin toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/nithila-randil/importease-backend/blob/main/main.py): `main.py`
- [Accounts and profiles](https://github.com/nithila-randil/importease-backend/blob/main/routes/auth_routes.py): `routes/auth_routes.py`
- [Token and role checks](https://github.com/nithila-randil/importease-backend/blob/main/dependencies.py): `dependencies.py`
- [Firestore client](https://github.com/nithila-randil/importease-backend/blob/main/firebase_setup.py): `firebase_setup.py`
- **Firestore database**
- **Firebase Authentication**

### Clearance marketplace

- [Agency directory](https://github.com/nithila-randil/importease-backend/blob/main/routes/agency_routes.py): `routes/agency_routes.py`
- [Shipment tracking](https://github.com/nithila-randil/importease-backend/blob/main/routes/shipment_routes.py): `routes/shipment_routes.py`
- [Tender and bids](https://github.com/nithila-randil/importease-backend/blob/main/routes/tender_routes.py): `routes/tender_routes.py`
- [Shipment documents](https://github.com/nithila-randil/importease-backend/blob/main/routes/document_routes.py): `routes/document_routes.py`
- [Notifications](https://github.com/nithila-randil/importease-backend/blob/main/routes/notification_routes.py): `routes/notification_routes.py`
- [Uploaded files](https://github.com/nithila-randil/importease-backend/blob/main/routes/document_routes.py): `routes/document_routes.py`

### Trade tools

- [HS-code services](https://github.com/nithila-randil/importease-backend/blob/main/routes/hscode_routes.py): `routes/hscode_routes.py`
- [Duty calculation](https://github.com/nithila-randil/importease-backend/blob/main/services/duty_calculator.py): `services/duty_calculator.py`
- **Pinecone search**
- **Exchange-rate service**
- [HS-code import](https://github.com/nithila-randil/importease-backend/blob/main/scripts/import_hscodes_from_pdf.py): `scripts/import_hscodes_from_pdf.py`

### Operations and oversight

- [Agent ratings](https://github.com/nithila-randil/importease-backend/blob/main/routes/agent_rating_routes.py): `routes/agent_rating_routes.py`
- [Agent verification](https://github.com/nithila-randil/importease-backend/blob/main/routes/agent_verification_routes.py): `routes/agent_verification_routes.py`
- [Administration](https://github.com/nithila-randil/importease-backend/blob/main/routes/admin_routes.py): `routes/admin_routes.py`
- [Messages](https://github.com/nithila-randil/importease-backend/blob/main/routes/message_routes.py): `routes/message_routes.py`

### Other components

- **Importer or agent**
- **Platform admin**

## Connections

- Importer or agent → FastAPI application: calls API
- Platform admin → FastAPI application: calls API
- FastAPI application → Accounts and profiles: routes to (evidence: `main.py`)
- FastAPI application → Agency directory: routes to (evidence: `main.py`)
- FastAPI application → HS-code services: routes to (evidence: `main.py`)
- FastAPI application → Shipment tracking: routes to (evidence: `main.py`)
- FastAPI application → Tender and bids: routes to (evidence: `main.py`)
- FastAPI application → Shipment documents: routes to (evidence: `main.py`)
- FastAPI application → Notifications: routes to (evidence: `main.py`)
- FastAPI application → Agent ratings: routes to (evidence: `main.py`)
- FastAPI application → Administration: routes to (evidence: `main.py`)
- FastAPI application → Agent verification: routes to (evidence: `main.py`)
- FastAPI application → Messages: routes to (evidence: `main.py`)
- Accounts and profiles → Firebase Authentication: creates users (evidence: `routes/auth_routes.py`)
- Token and role checks → Firebase Authentication: verifies tokens (evidence: `dependencies.py`)
- Accounts and profiles → Firestore database: reads and writes (evidence: `routes/auth_routes.py`)
- Agency directory → Firestore database: reads and writes (evidence: `routes/agency_routes.py`)
- Shipment tracking → Firestore database: reads and writes (evidence: `routes/shipment_routes.py`)
- Tender and bids → Firestore database: reads and writes (evidence: `routes/tender_routes.py`)
- Shipment documents → Firestore database: stores metadata (evidence: `routes/document_routes.py`)
- Shipment documents → Uploaded files: writes files (evidence: `routes/document_routes.py`)
- HS-code services → Firestore database: reads details (evidence: `routes/hscode_routes.py`)
- HS-code services → Pinecone search: searches codes (evidence: `routes/hscode_routes.py`)
- HS-code services → Exchange-rate service: fetches rates (evidence: `routes/hscode_routes.py`)
- HS-code services → Duty calculation: calculates duties (evidence: `routes/hscode_routes.py`)
- Shipment tracking → Notifications: creates alerts (evidence: `routes/shipment_routes.py`)
- Tender and bids → Notifications: creates alerts (evidence: `routes/tender_routes.py`)
- Notifications → Firestore database: reads and writes (evidence: `routes/notification_routes.py`)
- Agent ratings → Firestore database: uses database
- Agent verification → Firestore database: uses database
- Administration → Firestore database: reads and writes (evidence: `routes/admin_routes.py`)
- Messages → Firestore database: uses database
- HS-code import → Firestore database: imports catalogue
- Firestore client → Firestore database: initializes client (evidence: `firebase_setup.py`)