# wyeeeee/hajimi architecture

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

- Interactive diagram: https://gitdiagram.com/wyeeeee/hajimi
- Repository: https://github.com/wyeeeee/hajimi

## Overview

HAJIMI is a FastAPI proxy that accepts OpenAI-compatible chat and model requests, converts them for Gemini, and returns streamed or complete responses. A parallel Vertex AI mode provides model listing and chat completion. API keys, caching, limits, usage statistics, and configuration support the request lifecycle; web dashboards expose configuration, status, and logs, while the `page` UI also includes backend selection. Several dashboard and Vertex internals are unsampled, so uncertain UI/API wiring is marked unverified or omitted.

Main entry points: [`app/api/routes.py`](https://github.com/wyeeeee/hajimi/blob/main/app/api/routes.py) (API routes), [`app/main.py`](https://github.com/wyeeeee/hajimi/blob/main/app/main.py) (FastAPI app), [`app/api/nonstream_handlers.py`](https://github.com/wyeeeee/hajimi/blob/main/app/api/nonstream_handlers.py) (Completion handlers), [`app/vertex/routes/chat_api.py`](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/routes/chat_api.py) (Vertex chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Gemini proxy"]
  node_app["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_stream["Stream handlers<br/>[stream_handlers.py]"]
  node_nonstream["Completion handlers"]
  node_gemini["Gemini client<br/>[gemini.py]"]
  node_openai["OpenAI conversion<br/>[OpenAI.py]"]
end

subgraph group_vertex["Vertex mode"]
  node_vertexauth["Vertex auth<br/>[auth.py]"]
  node_vertexchat["Vertex chat<br/>[chat_api.py]"]
  node_vertexmodels["Vertex models API<br/>[models_api.py]"]
  node_vertexprocessing["Message processing"]
  node_vertexmodel_loader["Model loader<br/>[model_loader.py]"]
  node_vertexinit["Vertex initialization<br/>[vertex_ai_init.py]"]
  node_vertexconfig["Vertex configuration<br/>[config.py]"]
end

subgraph group_support["Shared services"]
  node_config["Runtime settings<br/>[settings.py]"]
  node_persistence[("Config persistence<br/>[persistence.py]")]
  node_keymgr["API key management<br/>[api_key.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_limits["Rate limits<br/>[rate_limiting.py]"]
  node_stats[("Usage statistics<br/>[stats.py]")]
  node_errors["Error handling<br/>[error_handling.py]"]
  node_logging[("Log management<br/>[logging.py]")]
end

subgraph group_ui["Web interfaces"]
  node_dashboard["Dashboard API<br/>[dashboard.py]"]
  node_hajimi_ui["Dashboard UI<br/>[DashboardView.vue]"]
  node_hajimi_store["Dashboard state<br/>[dashboard.js]"]
  node_page_ui["Unified web UI<br/>[DashboardView.vue]"]
  node_backend_store["Backend selection<br/>[backend.js]"]
end

node_caller(("API client"))
node_external_gemini(("Google Gemini"))
node_vertexservice(("Vertex AI"))

node_caller -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_routes
node_routes -->|"dispatches streaming"| node_stream
node_routes -->|"dispatches completion"| node_nonstream
node_routes -->|"validates with"| node_schemas
node_stream -->|"calls"| node_gemini
node_nonstream -->|"calls"| node_gemini
node_gemini -.->|"requests models"| node_external_gemini
node_routes -.->|"uses keys"| node_keymgr
node_nonstream -->|"reads and writes"| node_cache
node_nonstream -->|"updates usage"| node_stats
node_stream -->|"updates usage"| node_stats
node_nonstream -->|"handles failures"| node_errors
node_routes -.->|"applies limits"| node_limits
node_app -->|"initializes settings"| node_persistence
node_persistence -->|"loads and saves"| node_config
node_app -->|"initializes Vertex"| node_vertexinit
node_routes -->|"delegates model listing"| node_vertexmodels
node_routes -->|"delegates chat"| node_vertexchat
node_vertexchat -->|"checks credentials"| node_vertexauth
node_vertexmodels -->|"checks credentials"| node_vertexauth
node_vertexchat -->|"processes messages"| node_vertexprocessing
node_vertexmodels -->|"loads model list"| node_vertexmodel_loader
node_vertexinit -->|"initializes models"| node_vertexmodel_loader
node_vertexinit -->|"uses settings"| node_vertexconfig
node_vertexchat -.->|"sends inference"| node_vertexservice
node_app -.->|"mounts dashboard"| node_dashboard
node_hajimi_ui -->|"uses state"| node_hajimi_store
node_hajimi_store -.->|"requests dashboard data"| node_dashboard
node_page_ui -->|"uses backend state"| node_backend_store
node_page_ui -->|"uses dashboard state"| node_hajimi_store

click node_app "https://github.com/wyeeeee/hajimi/blob/main/app/main.py"
click node_routes "https://github.com/wyeeeee/hajimi/blob/main/app/api/routes.py"
click node_schemas "https://github.com/wyeeeee/hajimi/blob/main/app/models/schemas.py"
click node_stream "https://github.com/wyeeeee/hajimi/blob/main/app/api/stream_handlers.py"
click node_nonstream "https://github.com/wyeeeee/hajimi/blob/main/app/api/nonstream_handlers.py"
click node_gemini "https://github.com/wyeeeee/hajimi/blob/main/app/services/gemini.py"
click node_openai "https://github.com/wyeeeee/hajimi/blob/main/app/services/OpenAI.py"
click node_config "https://github.com/wyeeeee/hajimi/blob/main/app/config/settings.py"
click node_persistence "https://github.com/wyeeeee/hajimi/blob/main/app/config/persistence.py"
click node_keymgr "https://github.com/wyeeeee/hajimi/blob/main/app/utils/api_key.py"
click node_cache "https://github.com/wyeeeee/hajimi/blob/main/app/utils/cache.py"
click node_limits "https://github.com/wyeeeee/hajimi/blob/main/app/utils/rate_limiting.py"
click node_stats "https://github.com/wyeeeee/hajimi/blob/main/app/utils/stats.py"
click node_errors "https://github.com/wyeeeee/hajimi/blob/main/app/utils/error_handling.py"
click node_logging "https://github.com/wyeeeee/hajimi/blob/main/app/utils/logging.py"
click node_vertexauth "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/auth.py"
click node_vertexchat "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/routes/chat_api.py"
click node_vertexmodels "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/routes/models_api.py"
click node_vertexprocessing "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/message_processing.py"
click node_vertexmodel_loader "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/model_loader.py"
click node_vertexinit "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/vertex_ai_init.py"
click node_vertexconfig "https://github.com/wyeeeee/hajimi/blob/main/app/vertex/config.py"
click node_dashboard "https://github.com/wyeeeee/hajimi/blob/main/app/api/dashboard.py"
click node_hajimi_ui "https://github.com/wyeeeee/hajimi/blob/main/hajimiUI/src/views/DashboardView.vue"
click node_hajimi_store "https://github.com/wyeeeee/hajimi/blob/main/hajimiUI/src/stores/dashboard.js"
click node_page_ui "https://github.com/wyeeeee/hajimi/blob/main/page/src/views/DashboardView.vue"
click node_backend_store "https://github.com/wyeeeee/hajimi/blob/main/page/src/stores/backend.js"

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_routes,node_schemas,node_stream,node_nonstream,node_gemini,node_openai,node_caller toneBlue
class node_vertexauth,node_vertexchat,node_vertexmodels,node_vertexprocessing,node_vertexmodel_loader,node_vertexinit,node_vertexconfig toneAmber
class node_config,node_persistence,node_keymgr,node_cache,node_limits,node_stats,node_errors,node_logging toneMint
class node_dashboard,node_hajimi_ui,node_hajimi_store,node_page_ui,node_backend_store toneRose
class node_external_gemini,node_vertexservice toneIndigo
```

## Components

### Gemini proxy

- [FastAPI app](https://github.com/wyeeeee/hajimi/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/wyeeeee/hajimi/blob/main/app/api/routes.py): `app/api/routes.py`
- [Request schemas](https://github.com/wyeeeee/hajimi/blob/main/app/models/schemas.py): `app/models/schemas.py`
- [Stream handlers](https://github.com/wyeeeee/hajimi/blob/main/app/api/stream_handlers.py): `app/api/stream_handlers.py`
- [Completion handlers](https://github.com/wyeeeee/hajimi/blob/main/app/api/nonstream_handlers.py): `app/api/nonstream_handlers.py`
- [Gemini client](https://github.com/wyeeeee/hajimi/blob/main/app/services/gemini.py): `app/services/gemini.py`
- [OpenAI conversion](https://github.com/wyeeeee/hajimi/blob/main/app/services/OpenAI.py): `app/services/OpenAI.py`

### Vertex mode

- [Vertex auth](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/auth.py): `app/vertex/auth.py`
- [Vertex chat](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/routes/chat_api.py): `app/vertex/routes/chat_api.py`
- [Vertex models API](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/routes/models_api.py): `app/vertex/routes/models_api.py`
- [Message processing](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/message_processing.py): `app/vertex/message_processing.py`
- [Model loader](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/model_loader.py): `app/vertex/model_loader.py`
- [Vertex initialization](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/vertex_ai_init.py): `app/vertex/vertex_ai_init.py`
- [Vertex configuration](https://github.com/wyeeeee/hajimi/blob/main/app/vertex/config.py): `app/vertex/config.py`

### Shared services

- [Runtime settings](https://github.com/wyeeeee/hajimi/blob/main/app/config/settings.py): `app/config/settings.py`
- [Config persistence](https://github.com/wyeeeee/hajimi/blob/main/app/config/persistence.py): `app/config/persistence.py`
- [API key management](https://github.com/wyeeeee/hajimi/blob/main/app/utils/api_key.py): `app/utils/api_key.py`
- [Response cache](https://github.com/wyeeeee/hajimi/blob/main/app/utils/cache.py): `app/utils/cache.py`
- [Rate limits](https://github.com/wyeeeee/hajimi/blob/main/app/utils/rate_limiting.py): `app/utils/rate_limiting.py`
- [Usage statistics](https://github.com/wyeeeee/hajimi/blob/main/app/utils/stats.py): `app/utils/stats.py`
- [Error handling](https://github.com/wyeeeee/hajimi/blob/main/app/utils/error_handling.py): `app/utils/error_handling.py`
- [Log management](https://github.com/wyeeeee/hajimi/blob/main/app/utils/logging.py): `app/utils/logging.py`

### Web interfaces

- [Dashboard API](https://github.com/wyeeeee/hajimi/blob/main/app/api/dashboard.py): `app/api/dashboard.py`
- [Dashboard UI](https://github.com/wyeeeee/hajimi/blob/main/hajimiUI/src/views/DashboardView.vue): `hajimiUI/src/views/DashboardView.vue`
- [Dashboard state](https://github.com/wyeeeee/hajimi/blob/main/hajimiUI/src/stores/dashboard.js): `hajimiUI/src/stores/dashboard.js`
- [Unified web UI](https://github.com/wyeeeee/hajimi/blob/main/page/src/views/DashboardView.vue): `page/src/views/DashboardView.vue`
- [Backend selection](https://github.com/wyeeeee/hajimi/blob/main/page/src/stores/backend.js): `page/src/stores/backend.js`

### Other components

- **API client**
- **Google Gemini**
- **Vertex AI**

## Connections

- API client → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → API routes: mounts routes (evidence: `app/main.py`)
- API routes → Stream handlers: dispatches streaming (evidence: `app/api/routes.py`)
- API routes → Completion handlers: dispatches completion (evidence: `app/api/routes.py`)
- API routes → Request schemas: validates with (evidence: `app/api/routes.py`)
- Stream handlers → Gemini client: calls (evidence: `app/api/stream_handlers.py`)
- Completion handlers → Gemini client: calls (evidence: `app/api/nonstream_handlers.py`)
- Gemini client → Google Gemini: requests models
- API routes → API key management: uses keys
- Completion handlers → Response cache: reads and writes (evidence: `app/api/nonstream_handlers.py`)
- Completion handlers → Usage statistics: updates usage (evidence: `app/api/nonstream_handlers.py`)
- Stream handlers → Usage statistics: updates usage (evidence: `app/api/stream_handlers.py`)
- Completion handlers → Error handling: handles failures (evidence: `app/api/nonstream_handlers.py`)
- API routes → Rate limits: applies limits
- FastAPI app → Config persistence: initializes settings (evidence: `app/main.py`)
- Config persistence → Runtime settings: loads and saves (evidence: `app/config/persistence.py`)
- FastAPI app → Vertex initialization: initializes Vertex (evidence: `app/main.py`)
- API routes → Vertex models API: delegates model listing (evidence: `app/api/routes.py`)
- API routes → Vertex chat: delegates chat (evidence: `app/api/routes.py`)
- Vertex chat → Vertex auth: checks credentials (evidence: `app/vertex/routes/chat_api.py`)
- Vertex models API → Vertex auth: checks credentials (evidence: `app/vertex/routes/models_api.py`)
- Vertex chat → Message processing: processes messages (evidence: `app/vertex/routes/chat_api.py`)
- Vertex models API → Model loader: loads model list (evidence: `app/vertex/routes/models_api.py`)
- Vertex initialization → Model loader: initializes models (evidence: `app/vertex/vertex_ai_init.py`)
- Vertex initialization → Vertex configuration: uses settings (evidence: `app/vertex/vertex_ai_init.py`)
- Vertex chat → Vertex AI: sends inference
- FastAPI app → Dashboard API: mounts dashboard
- Dashboard UI → Dashboard state: uses state (evidence: `hajimiUI/src/views/DashboardView.vue`)
- Dashboard state → Dashboard API: requests dashboard data
- Unified web UI → Backend selection: uses backend state (evidence: `page/src/views/DashboardView.vue`)
- Unified web UI → Dashboard state: uses dashboard state (evidence: `page/src/views/DashboardView.vue`)
