# dheerajll/track-it-now-v1 architecture

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

- Interactive diagram: https://gitdiagram.com/dheerajll/track-it-now-v1
- Repository: https://github.com/dheerajll/track-it-now-v1

## Overview

Parcel Tracer is a FastAPI backend for parcel requests, delivery assignment and status, account management, and real-time agent/location updates. The main customer workflow is request → receiver acceptance → parcel creation → agent assignment and tracking; customers and agents interact through REST endpoints and WebSockets. Services mediate API operations and repositories persist domain records in PostgreSQL, while Redis supports agent-location and regional pub/sub behavior. The graph reflects the README and sampled source; unsampled modules are included only where the tree or README establishes their role, so uncertain internal wiring is omitted.

Main entry points: [`app/main.py`](https://github.com/dheerajll/track-it-now-v1/blob/main/app/main.py) (FastAPI application), [`app/services/delivery_services.py`](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/delivery_services.py) (Delivery assignment), [`app/api/parcels.py`](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/parcels.py) (Parcel routes), [`app/services/users.py`](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/users.py) (User services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP and WebSocket API"]
  node_app["FastAPI application<br/>[main.py]"]
  node_users_api["Account routes<br/>[users.py]"]
  node_parcels_api["Parcel routes<br/>[parcels.py]"]
  node_agents_api["Agent routes<br/>[agents.py]"]
  node_delivery_api["Delivery routes<br/>[delivery.py]"]
  node_track_api["Tracking routes<br/>[track.py]"]
end

subgraph group_domain["Domain services"]
  node_users_service["User services<br/>[users.py]"]
  node_request_service["Request services<br/>[parcel_requests.py]"]
  node_parcel_service["Parcel services<br/>[parcels.py]"]
  node_delivery_service["Delivery assignment"]
end

subgraph group_realtime["Live coordination"]
  node_agent_service["Agent coordination<br/>[agent.py]"]
  node_location_service["Live location<br/>[livelocation.py]"]
  node_websocket_service["WebSocket managers<br/>[websockets.py]"]
  node_redis[("Redis")]
end

subgraph group_persistence["Persistence and security"]
  node_user_repo["User repository<br/>[users.py]"]
  node_request_repo["Request repository<br/>[parcel_requests.py]"]
  node_parcel_repo["Parcel repository<br/>[parcels.py]"]
  node_delivery_repo["Delivery repository"]
  node_tracking_repo["Tracking code repository<br/>[trackingcode.py]"]
  node_postgres[("PostgreSQL")]
  node_session["Database session<br/>[session.py]"]
  node_security["Password and tokens<br/>[security.py]"]
end

node_customer(("Customer"))
node_agent(("Delivery agent"))

node_customer -->|"uses API"| node_app
node_agent -->|"uses API"| node_app
node_app -->|"registers routes"| node_users_api
node_app -->|"registers routes"| node_parcels_api
node_app -->|"registers routes"| node_agents_api
node_app -->|"registers routes"| node_delivery_api
node_app -->|"registers routes"| node_track_api
node_users_api -->|"calls"| node_users_service
node_users_service -->|"uses"| node_user_repo
node_users_service -->|"uses"| node_security
node_parcels_api -->|"calls"| node_request_service
node_parcels_api -->|"calls"| node_parcel_service
node_request_service -->|"uses"| node_request_repo
node_request_service -->|"notifies"| node_websocket_service
node_parcel_service -->|"uses"| node_parcel_repo
node_delivery_api -->|"calls"| node_delivery_service
node_delivery_service -->|"creates assignment"| node_delivery_repo
node_delivery_service -->|"creates code"| node_tracking_repo
node_delivery_service -->|"updates status"| node_parcel_service
node_delivery_service -->|"sends notifications"| node_websocket_service
node_agents_api -->|"dispatches"| node_agent_service
node_agent_service -->|"publishes locations"| node_redis
node_agent_service -->|"forwards updates"| node_websocket_service
node_track_api -->|"handles tracking"| node_location_service
node_location_service -.->|"uses location data"| node_redis
node_app -->|"opens and closes"| node_session
node_session -->|"initializes pool"| node_postgres
node_user_repo -->|"reads and writes"| node_postgres
node_request_repo -->|"reads and writes"| node_postgres
node_parcel_repo -->|"reads and writes"| node_postgres
node_delivery_repo -->|"persists assignments"| node_postgres
node_tracking_repo -->|"persists codes"| node_postgres

click node_app "https://github.com/dheerajll/track-it-now-v1/blob/main/app/main.py"
click node_users_api "https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/users.py"
click node_parcels_api "https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/parcels.py"
click node_agents_api "https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/agents.py"
click node_delivery_api "https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/delivery.py"
click node_track_api "https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/track.py"
click node_users_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/users.py"
click node_request_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/parcel_requests.py"
click node_parcel_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/parcels.py"
click node_delivery_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/delivery_services.py"
click node_agent_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/agent.py"
click node_location_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/livelocation.py"
click node_websocket_service "https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/websockets.py"
click node_user_repo "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/users.py"
click node_request_repo "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/parcel_requests.py"
click node_parcel_repo "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/parcels.py"
click node_delivery_repo "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/delivery_assignment.py"
click node_tracking_repo "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/trackingcode.py"
click node_session "https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/session.py"
click node_security "https://github.com/dheerajll/track-it-now-v1/blob/main/app/core/security.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_app,node_users_api,node_parcels_api,node_agents_api,node_delivery_api,node_track_api toneBlue
class node_users_service,node_request_service,node_parcel_service,node_delivery_service toneAmber
class node_agent_service,node_location_service,node_websocket_service,node_redis toneMint
class node_user_repo,node_request_repo,node_parcel_repo,node_delivery_repo,node_tracking_repo,node_postgres,node_session,node_security toneRose
class node_customer,node_agent toneIndigo
```

## Components

### HTTP and WebSocket API

- [FastAPI application](https://github.com/dheerajll/track-it-now-v1/blob/main/app/main.py): `app/main.py`
- [Account routes](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/users.py): `app/api/users.py`
- [Parcel routes](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/parcels.py): `app/api/parcels.py`
- [Agent routes](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/agents.py): `app/api/agents.py`
- [Delivery routes](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/delivery.py): `app/api/delivery.py`
- [Tracking routes](https://github.com/dheerajll/track-it-now-v1/blob/main/app/api/track.py): `app/api/track.py`

### Domain services

- [User services](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/users.py): `app/services/users.py`
- [Request services](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/parcel_requests.py): `app/services/parcel_requests.py`
- [Parcel services](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/parcels.py): `app/services/parcels.py`
- [Delivery assignment](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/delivery_services.py): `app/services/delivery_services.py`

### Live coordination

- [Agent coordination](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/agent.py): `app/services/agent.py`
- [Live location](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/livelocation.py): `app/services/livelocation.py`
- [WebSocket managers](https://github.com/dheerajll/track-it-now-v1/blob/main/app/services/websockets.py): `app/services/websockets.py`
- **Redis**

### Persistence and security

- [User repository](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/users.py): `app/database/repository/users.py`
- [Request repository](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/parcel_requests.py): `app/database/repository/parcel_requests.py`
- [Parcel repository](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/parcels.py): `app/database/repository/parcels.py`
- [Delivery repository](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/delivery_assignment.py): `app/database/repository/delivery_assignment.py`
- [Tracking code repository](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/repository/trackingcode.py): `app/database/repository/trackingcode.py`
- **PostgreSQL**
- [Database session](https://github.com/dheerajll/track-it-now-v1/blob/main/app/database/session.py): `app/database/session.py`
- [Password and tokens](https://github.com/dheerajll/track-it-now-v1/blob/main/app/core/security.py): `app/core/security.py`

### Other components

- **Customer**
- **Delivery agent**

## Connections

- Customer → FastAPI application: uses API
- Delivery agent → FastAPI application: uses API
- FastAPI application → Account routes: registers routes
- FastAPI application → Parcel routes: registers routes
- FastAPI application → Agent routes: registers routes
- FastAPI application → Delivery routes: registers routes
- FastAPI application → Tracking routes: registers routes
- Account routes → User services: calls
- User services → User repository: uses
- User services → Password and tokens: uses
- Parcel routes → Request services: calls
- Parcel routes → Parcel services: calls
- Request services → Request repository: uses
- Request services → WebSocket managers: notifies
- Parcel services → Parcel repository: uses
- Delivery routes → Delivery assignment: calls
- Delivery assignment → Delivery repository: creates assignment
- Delivery assignment → Tracking code repository: creates code
- Delivery assignment → Parcel services: updates status
- Delivery assignment → WebSocket managers: sends notifications
- Agent routes → Agent coordination: dispatches
- Agent coordination → Redis: publishes locations
- Agent coordination → WebSocket managers: forwards updates
- Tracking routes → Live location: handles tracking
- Live location → Redis: uses location data
- FastAPI application → Database session: opens and closes
- Database session → PostgreSQL: initializes pool
- User repository → PostgreSQL: reads and writes
- Request repository → PostgreSQL: reads and writes
- Parcel repository → PostgreSQL: reads and writes
- Delivery repository → PostgreSQL: persists assignments
- Tracking code repository → PostgreSQL: persists codes