# barkhai-ux/api_provider architecture

> Architecture diagram of the GitHub repository barkhai-ux/api_provider, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barkhai-ux/api_provider
- Repository: https://github.com/barkhai-ux/api_provider

## Overview

Ubhub is a Mongolia-focused location API and developer platform. A customer submits a versioned geocoding, reverse-geocoding, or routing request; the API authorizes and rate-limits it through Convex, obtains location data through the ArcGIS adapter, and returns the public contract. The website adds an isolated public-map demo, account and key management, a playground, billing, and live usage views; an SDK supports customer applications. The README documents these cross-service flows and capabilities; several web and Convex internals are unsampled, so their finer-grained links are not inferred.

Main entry points: [`apps/api/app/main.py`](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/main.py) (FastAPI application), [`apps/api/app/services/geo/factory.py`](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/factory.py) (Provider factory), [`apps/convex/convex/usage.ts`](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/usage.ts) (Usage and rollups), [`apps/web/components/dashboard/overview-view.tsx`](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/dashboard/overview-view.tsx) (Console dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Website"]
  node_web_map["Public map and demo<br/>[map-app.tsx]"]
  node_web_portal["Developer portal<br/>[page.tsx]"]
  node_web_auth["Account screens<br/>[login-form.tsx]"]
  node_web_dashboard["Console dashboard<br/>[overview-view.tsx]"]
  node_web_playground["API playground<br/>[playground.tsx]"]
  node_web_proxy["Playground token route<br/>[route.ts]"]
end

subgraph group_api["Public API"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_api_routes["Versioned endpoints<br/>[routing.py]"]
  node_api_demo["Demo endpoints<br/>[demo.py]"]
  node_api_auth["Request authorization<br/>[deps.py]"]
  node_api_controls["Request controls<br/>[middleware.py]"]
  node_api_gateway["Convex gateway client<br/>[gateway.py]"]
  node_api_usage["Usage recorder<br/>[usage.py]"]
  node_api_cache["API caches<br/>[cache.py]"]
end

subgraph group_geo["Geo Services"]
  node_geo_factory["Provider factory<br/>[factory.py]"]
  node_geo_geocoding["Geocoding services<br/>[geocoding.py]"]
  node_geo_routing["Routing service<br/>[routing.py]"]
  node_geo_graph["Road graph and search<br/>[road_graph.py]"]
  node_arcgis_client["ArcGIS REST adapter<br/>[client.py]"]
  node_arcgis_auth["ArcGIS authentication<br/>[auth.py]"]
  node_arcgis_providers["ArcGIS providers<br/>[providers.py]"]
end

subgraph group_platform["Accounts and Operations"]
  node_convex_auth["Accounts and sessions<br/>[auth.ts]"]
  node_convex_keys[("API keys<br/>[apiKeys.ts]")]
  node_convex_gateway["Gateway authorization<br/>[gateway.ts]"]
  node_convex_usage[("Usage and rollups<br/>[usage.ts]")]
  node_convex_payments["Billing and payments<br/>[payments.ts]"]
  node_convex_schema[("Platform data model<br/>[schema.ts]")]
end

subgraph group_sdk["Client SDK"]
  node_client_sdk["TypeScript API client<br/>[client.ts]"]
  node_api_types["Shared API types<br/>[index.ts]"]
end

node_browser(("Browser users"))
node_developer(("Customer apps"))
node_arcgis["ArcGIS FeatureServer"]

node_browser -->|"uses map"| node_web_map
node_browser -->|"visits portal"| node_web_portal
node_browser -->|"signs in"| node_web_auth
node_browser -->|"views console"| node_web_dashboard
node_browser -->|"tries API"| node_web_playground
node_developer -->|"sends requests"| node_api_entry
node_web_map -->|"calls demo API"| node_api_entry
node_web_playground -->|"calls public API"| node_api_entry
node_web_proxy -->|"issues token"| node_convex_keys
node_web_dashboard -->|"subscribes live"| node_convex_usage
node_web_auth -->|"authenticates"| node_convex_auth
node_api_entry -->|"mounts routes"| node_api_routes
node_api_entry -->|"mounts routes"| node_api_demo
node_api_routes -->|"requires principal"| node_api_auth
node_api_entry -->|"applies middleware"| node_api_controls
node_api_auth -->|"authorizes key"| node_api_gateway
node_api_auth -->|"caches key data"| node_api_cache
node_api_gateway -->|"calls gateway"| node_convex_gateway
node_api_usage -->|"records usage"| node_convex_usage
node_api_routes -->|"uses geo services"| node_geo_factory
node_api_demo -->|"uses geo services"| node_geo_factory
node_geo_factory -.->|"provides geocoding"| node_geo_geocoding
node_geo_factory -.->|"provides routing"| node_geo_routing
node_geo_factory -->|"wires providers"| node_arcgis_providers
node_geo_routing -->|"uses road graph"| node_geo_graph
node_arcgis_providers -->|"uses adapter"| node_arcgis_client
node_arcgis_client -->|"uses token provider"| node_arcgis_auth
node_arcgis_client -->|"queries layers"| node_arcgis
node_api_entry -->|"records requests"| node_api_usage
node_client_sdk -->|"calls /v1"| node_api_entry
node_client_sdk -->|"uses types"| node_api_types
node_convex_gateway -->|"checks credentials"| node_convex_keys
node_convex_gateway -->|"tracks requests"| node_convex_usage
node_convex_keys -.->|"stores key records"| node_convex_schema
node_convex_usage -.->|"stores usage data"| node_convex_schema
node_web_dashboard -.->|"manages billing"| node_convex_payments
node_convex_auth -.->|"stores account data"| node_convex_schema

click node_web_map "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/map/map-app.tsx"
click node_web_portal "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/app/(site)/developers/page.tsx"
click node_web_auth "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/auth/login-form.tsx"
click node_web_dashboard "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/dashboard/overview-view.tsx"
click node_web_playground "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/playground/playground.tsx"
click node_web_proxy "https://github.com/barkhai-ux/api_provider/blob/main/apps/web/app/api/playground/token/route.ts"
click node_api_entry "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/main.py"
click node_api_routes "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/v1/routing.py"
click node_api_demo "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/demo.py"
click node_api_auth "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/deps.py"
click node_api_controls "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/core/middleware.py"
click node_api_gateway "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/gateway.py"
click node_api_usage "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/usage.py"
click node_api_cache "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/cache.py"
click node_geo_factory "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/factory.py"
click node_geo_geocoding "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/geocoding.py"
click node_geo_routing "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/routing.py"
click node_geo_graph "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/road_graph.py"
click node_arcgis_client "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/client.py"
click node_arcgis_auth "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/auth.py"
click node_arcgis_providers "https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/providers.py"
click node_convex_auth "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/auth.ts"
click node_convex_keys "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/apiKeys.ts"
click node_convex_gateway "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/gateway.ts"
click node_convex_usage "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/usage.ts"
click node_convex_payments "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/payments.ts"
click node_convex_schema "https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/schema.ts"
click node_client_sdk "https://github.com/barkhai-ux/api_provider/blob/main/packages/api-client/src/client.ts"
click node_api_types "https://github.com/barkhai-ux/api_provider/blob/main/packages/types/src/index.ts"

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_web_map,node_web_portal,node_web_auth,node_web_dashboard,node_web_playground,node_web_proxy,node_browser toneBlue
class node_api_entry,node_api_routes,node_api_demo,node_api_auth,node_api_controls,node_api_gateway,node_api_usage,node_api_cache toneAmber
class node_geo_factory,node_geo_geocoding,node_geo_routing,node_geo_graph,node_arcgis_client,node_arcgis_auth,node_arcgis_providers,node_arcgis toneMint
class node_convex_auth,node_convex_keys,node_convex_gateway,node_convex_usage,node_convex_payments,node_convex_schema toneRose
class node_client_sdk,node_api_types,node_developer toneIndigo
```

## Components

### Website

- [Public map and demo](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/map/map-app.tsx): `apps/web/components/map/map-app.tsx`
- [Developer portal](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/app/(site)/developers/page.tsx): `apps/web/app/(site)/developers/page.tsx`
- [Account screens](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/auth/login-form.tsx): `apps/web/components/auth/login-form.tsx`
- [Console dashboard](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/dashboard/overview-view.tsx): `apps/web/components/dashboard/overview-view.tsx`
- [API playground](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/components/playground/playground.tsx): `apps/web/components/playground/playground.tsx`
- [Playground token route](https://github.com/barkhai-ux/api_provider/blob/main/apps/web/app/api/playground/token/route.ts): `apps/web/app/api/playground/token/route.ts`

### Public API

- [FastAPI application](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Versioned endpoints](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/v1/routing.py): `apps/api/app/api/v1/routing.py`
- [Demo endpoints](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/demo.py): `apps/api/app/api/demo.py`
- [Request authorization](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/api/deps.py): `apps/api/app/api/deps.py`
- [Request controls](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/core/middleware.py): `apps/api/app/core/middleware.py`
- [Convex gateway client](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/gateway.py): `apps/api/app/services/gateway.py`
- [Usage recorder](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/usage.py): `apps/api/app/services/usage.py`
- [API caches](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/cache.py): `apps/api/app/services/cache.py`

### Geo Services

- [Provider factory](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/factory.py): `apps/api/app/services/geo/factory.py`
- [Geocoding services](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/geocoding.py): `apps/api/app/services/geo/geocoding.py`
- [Routing service](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/routing.py): `apps/api/app/services/geo/routing.py`
- [Road graph and search](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/geo/road_graph.py): `apps/api/app/services/geo/road_graph.py`
- [ArcGIS REST adapter](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/client.py): `apps/api/app/services/arcgis/client.py`
- [ArcGIS authentication](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/auth.py): `apps/api/app/services/arcgis/auth.py`
- [ArcGIS providers](https://github.com/barkhai-ux/api_provider/blob/main/apps/api/app/services/arcgis/providers.py): `apps/api/app/services/arcgis/providers.py`

### Accounts and Operations

- [Accounts and sessions](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/auth.ts): `apps/convex/convex/auth.ts`
- [API keys](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/apiKeys.ts): `apps/convex/convex/apiKeys.ts`
- [Gateway authorization](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/gateway.ts): `apps/convex/convex/gateway.ts`
- [Usage and rollups](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/usage.ts): `apps/convex/convex/usage.ts`
- [Billing and payments](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/payments.ts): `apps/convex/convex/payments.ts`
- [Platform data model](https://github.com/barkhai-ux/api_provider/blob/main/apps/convex/convex/schema.ts): `apps/convex/convex/schema.ts`

### Client SDK

- [TypeScript API client](https://github.com/barkhai-ux/api_provider/blob/main/packages/api-client/src/client.ts): `packages/api-client/src/client.ts`
- [Shared API types](https://github.com/barkhai-ux/api_provider/blob/main/packages/types/src/index.ts): `packages/types/src/index.ts`

### Other components

- **Browser users**
- **Customer apps**
- **ArcGIS FeatureServer**

## Connections

- Browser users → Public map and demo: uses map
- Browser users → Developer portal: visits portal
- Browser users → Account screens: signs in
- Browser users → Console dashboard: views console
- Browser users → API playground: tries API
- Customer apps → FastAPI application: sends requests
- Public map and demo → FastAPI application: calls demo API
- API playground → FastAPI application: calls public API
- Playground token route → API keys: issues token (evidence: `apps/web/app/api/playground/token/route.ts`)
- Console dashboard → Usage and rollups: subscribes live
- Account screens → Accounts and sessions: authenticates
- FastAPI application → Versioned endpoints: mounts routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Demo endpoints: mounts routes (evidence: `apps/api/app/main.py`)
- Versioned endpoints → Request authorization: requires principal (evidence: `apps/api/app/api/v1/routing.py`)
- FastAPI application → Request controls: applies middleware (evidence: `apps/api/app/core/middleware.py`)
- Request authorization → Convex gateway client: authorizes key (evidence: `apps/api/app/api/deps.py`)
- Request authorization → API caches: caches key data (evidence: `apps/api/app/api/deps.py`)
- Convex gateway client → Gateway authorization: calls gateway
- Usage recorder → Usage and rollups: records usage
- Versioned endpoints → Provider factory: uses geo services
- Demo endpoints → Provider factory: uses geo services (evidence: `apps/api/app/api/demo.py`)
- Provider factory → Geocoding services: provides geocoding
- Provider factory → Routing service: provides routing
- Provider factory → ArcGIS providers: wires providers
- Routing service → Road graph and search: uses road graph
- ArcGIS providers → ArcGIS REST adapter: uses adapter
- ArcGIS REST adapter → ArcGIS authentication: uses token provider (evidence: `apps/api/app/services/arcgis/client.py`)
- ArcGIS REST adapter → ArcGIS FeatureServer: queries layers
- FastAPI application → Usage recorder: records requests (evidence: `apps/api/app/main.py`)
- TypeScript API client → FastAPI application: calls /v1
- TypeScript API client → Shared API types: uses types (evidence: `packages/api-client/src/client.ts`)
- Gateway authorization → API keys: checks credentials
- Gateway authorization → Usage and rollups: tracks requests
- API keys → Platform data model: stores key records
- Usage and rollups → Platform data model: stores usage data
- Console dashboard → Billing and payments: manages billing
- Accounts and sessions → Platform data model: stores account data
