# asav-mx/j-tel architecture

> Architecture diagram of the GitHub repository asav-mx/j-tel, 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/asav-mx/j-tel
- Repository: https://github.com/asav-mx/j-tel

## Overview

JTEL is a multi-account platform for verifying employee transportation services. Client organizations configure sites, contracts, geofences, routes, shifts and services; carriers manage vehicles and contribute operational evidence; platform staff administer circuits and investigate exceptions. GPS ingestion and scheduled verification feed compliance results, which users monitor and receive as alerts. A separate public app exposes live transit information and ticket-validation workflows. The supplied excerpts show selected API and service calls; several broader subsystem connections are documented or suggested by the tree but are left unwired where implementation evidence is missing.

Main entry points: [`packages/services`](https://github.com/asav-mx/j-tel/tree/main/packages/services) (Verification and ingestion), [`apps/web/src/app/api/cron`](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cron) (Verification jobs API), [`apps/publico/src/app`](https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/app) (Rider app), [`apps/web/src/app/api/cliente`](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cliente) (Client configuration API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configure["Client setup"]
  node_configapi["Client configuration API"]
  node_configdata["Client configuration data"]
end

subgraph group_operations["Fleet operations"]
  node_fleetapi["Carrier operations API"]
  node_fleetdata["Fleet and service data"]
  node_gpsadapter["GPS integration"]
end

subgraph group_verify["Verification"]
  node_cronapi["Verification jobs API"]
  node_services["Verification and ingestion"]
  node_decision["Decision engine"]
  node_compliance[("Compliance records")]
  node_alerts["Alerting"]
  node_healthapi["Health endpoint<br/>[route.ts]"]
end

subgraph group_access["User experiences"]
  node_clientui["Client workspace"]
  node_carrierui["Carrier workspace"]
  node_staffui["J-Staff workspace"]
end

subgraph group_public["Public transit"]
  node_publicui["Rider app"]
  node_publicapi["Transit and ticket API"]
  node_ticketreader["Ticket reader"]
end

node_client(("Client operators"))
node_carrier(("Carrier operators"))
node_staff(("J-Staff operators"))
node_cron(("Scheduled jobs"))
node_gps(("GPS provider"))
node_email(("Alert channel"))
node_rider(("Transit riders"))
node_db[("PostgreSQL")]

node_client -->|"uses"| node_clientui
node_clientui -->|"submits configuration"| node_configapi
node_configapi -->|"reads and writes"| node_configdata
node_configdata -->|"persists"| node_db
node_carrier -->|"uses"| node_carrierui
node_carrierui -->|"submits operations"| node_fleetapi
node_fleetapi -->|"reads and writes"| node_fleetdata
node_fleetdata -->|"persists"| node_db
node_gpsadapter -.->|"fetches GPS data"| node_gps
node_cron -->|"invokes"| node_cronapi
node_cronapi -->|"orchestrates"| node_services
node_services -->|"requests decisions"| node_decision
node_services -->|"records outcomes"| node_compliance
node_compliance -->|"persists"| node_db
node_staff -->|"uses"| node_staffui
node_cronapi -->|"builds alerts"| node_alerts
node_alerts -.->|"sends notifications"| node_email
node_healthapi -->|"gets diagnosis"| node_services
node_rider -->|"uses"| node_publicui
node_publicui -->|"requests transit data"| node_publicapi
node_publicui -->|"scans tickets"| node_ticketreader
node_ticketreader -->|"synchronizes scans"| node_publicapi

click node_clientui "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/cliente"
click node_carrierui "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/carrier"
click node_staffui "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/jstaff"
click node_configapi "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cliente"
click node_configdata "https://github.com/asav-mx/j-tel/tree/main/packages/db"
click node_fleetapi "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/carrier"
click node_fleetdata "https://github.com/asav-mx/j-tel/tree/main/packages/db"
click node_gpsadapter "https://github.com/asav-mx/j-tel/tree/main/packages/gps-umbrella"
click node_cronapi "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cron"
click node_services "https://github.com/asav-mx/j-tel/tree/main/packages/services"
click node_decision "https://github.com/asav-mx/j-tel/tree/main/packages/verification"
click node_compliance "https://github.com/asav-mx/j-tel/tree/main/packages/db"
click node_alerts "https://github.com/asav-mx/j-tel/tree/main/apps/web/src/lib/alertas"
click node_healthapi "https://github.com/asav-mx/j-tel/blob/main/apps/web/src/app/api/salud/route.ts"
click node_publicui "https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/app"
click node_publicapi "https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/app/api"
click node_ticketreader "https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/lib/validador"

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_configapi,node_configdata,node_client toneBlue
class node_fleetapi,node_fleetdata,node_gpsadapter,node_db toneAmber
class node_cronapi,node_services,node_decision,node_compliance,node_alerts,node_healthapi toneMint
class node_clientui,node_carrierui,node_staffui toneRose
class node_publicui,node_publicapi,node_ticketreader,node_carrier,node_staff,node_cron,node_gps,node_email,node_rider toneIndigo
```

## Components

### Client setup

- [Client configuration API](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cliente): `apps/web/src/app/api/cliente`
- [Client configuration data](https://github.com/asav-mx/j-tel/tree/main/packages/db): `packages/db`

### Fleet operations

- [Carrier operations API](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/carrier): `apps/web/src/app/api/carrier`
- [Fleet and service data](https://github.com/asav-mx/j-tel/tree/main/packages/db): `packages/db`
- [GPS integration](https://github.com/asav-mx/j-tel/tree/main/packages/gps-umbrella): `packages/gps-umbrella`

### Verification

- [Verification jobs API](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/api/cron): `apps/web/src/app/api/cron`
- [Verification and ingestion](https://github.com/asav-mx/j-tel/tree/main/packages/services): `packages/services`
- [Decision engine](https://github.com/asav-mx/j-tel/tree/main/packages/verification): `packages/verification`
- [Compliance records](https://github.com/asav-mx/j-tel/tree/main/packages/db): `packages/db`
- [Alerting](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/lib/alertas): `apps/web/src/lib/alertas`
- [Health endpoint](https://github.com/asav-mx/j-tel/blob/main/apps/web/src/app/api/salud/route.ts): `apps/web/src/app/api/salud/route.ts`

### User experiences

- [Client workspace](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/cliente): `apps/web/src/app/cliente`
- [Carrier workspace](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/carrier): `apps/web/src/app/carrier`
- [J-Staff workspace](https://github.com/asav-mx/j-tel/tree/main/apps/web/src/app/jstaff): `apps/web/src/app/jstaff`

### Public transit

- [Rider app](https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/app): `apps/publico/src/app`
- [Transit and ticket API](https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/app/api): `apps/publico/src/app/api`
- [Ticket reader](https://github.com/asav-mx/j-tel/tree/main/apps/publico/src/lib/validador): `apps/publico/src/lib/validador`

### Other components

- **Client operators**
- **Carrier operators**
- **J-Staff operators**
- **Scheduled jobs**
- **GPS provider**
- **Alert channel**
- **Transit riders**
- **PostgreSQL**

## Connections

- Client operators → Client workspace: uses
- Client workspace → Client configuration API: submits configuration
- Client configuration API → Client configuration data: reads and writes
- Client configuration data → PostgreSQL: persists
- Carrier operators → Carrier workspace: uses
- Carrier workspace → Carrier operations API: submits operations
- Carrier operations API → Fleet and service data: reads and writes
- Fleet and service data → PostgreSQL: persists
- GPS integration → GPS provider: fetches GPS data
- Scheduled jobs → Verification jobs API: invokes
- Verification jobs API → Verification and ingestion: orchestrates
- Verification and ingestion → Decision engine: requests decisions
- Verification and ingestion → Compliance records: records outcomes
- Compliance records → PostgreSQL: persists
- J-Staff operators → J-Staff workspace: uses
- Verification jobs API → Alerting: builds alerts
- Alerting → Alert channel: sends notifications
- Health endpoint → Verification and ingestion: gets diagnosis
- Transit riders → Rider app: uses
- Rider app → Transit and ticket API: requests transit data
- Rider app → Ticket reader: scans tickets
- Ticket reader → Transit and ticket API: synchronizes scans