# malvolt/voldt-api architecture

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

- Interactive diagram: https://gitdiagram.com/malvolt/voldt-api
- Repository: https://github.com/malvolt/voldt-api

## Overview

Voldt API is a modular Fastify REST API. Clients call domain endpoints; the app initializes request statistics and uses a route loader to discover and register route modules, which return endpoint results. The route tree covers AI, discovery, downloads, search, temporary mail, and utility services. The app also serves static pages and generated OpenAPI documentation. Sampled source confirms the routing, stats, and selected search and AI integrations; other route internals are represented by their directory, with no unsampled service calls inferred.

Main entry points: [`src/lib/loadRoutes.ts`](https://github.com/malvolt/voldt-api/blob/main/src/lib/loadRoutes.ts) (Route loader), [`src/app.ts`](https://github.com/malvolt/voldt-api/blob/main/src/app.ts) (Fastify app), [`src/routes`](https://github.com/malvolt/voldt-api/tree/main/src/routes) (Search endpoints), [`src/stats.ts`](https://github.com/malvolt/voldt-api/blob/main/src/stats.ts) (Request counters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API runtime"]
  node_app["Fastify app<br/>[app.ts]"]
  node_loader["Route loader<br/>[loadRoutes.ts]"]
end

subgraph group_ai["AI services"]
  node_ai_routes["AI endpoints"]
end

subgraph group_content["Content services"]
  node_discovery["Discovery endpoints"]
  node_download["Download endpoints"]
end

subgraph group_utilities["Search and tools"]
  node_search["Search endpoints"]
  node_tempmail["Temporary mail"]
  node_tools["Utility endpoints"]
end

subgraph group_state["Stats and web"]
  node_stats["Request counters<br/>[stats.ts]"]
  node_stats_file[("Stats file<br/>[stats.json]")]
  node_web["Static pages"]
  node_openapi["OpenAPI docs<br/>[app.ts]"]
end

node_client(("API client"))
node_notegpt["NoteGPT service"]
node_mal["MyAnimeList"]
node_bing["Bing Search"]

node_client -->|"sends requests"| node_app
node_app -->|"loads routes"| node_loader
node_loader -->|"imports modules"| node_ai_routes
node_loader -->|"imports modules"| node_discovery
node_loader -->|"imports modules"| node_download
node_loader -->|"imports modules"| node_search
node_loader -->|"imports modules"| node_tempmail
node_loader -->|"imports modules"| node_tools
node_app -->|"updates counters"| node_stats
node_stats -->|"reads and writes"| node_stats_file
node_app -->|"serves pages"| node_web
node_app -->|"serves spec"| node_openapi
node_search -->|"queries details"| node_mal
node_search -->|"fetches results"| node_bing
node_ai_routes -->|"submits image jobs"| node_notegpt

click node_app "https://github.com/malvolt/voldt-api/blob/main/src/app.ts"
click node_loader "https://github.com/malvolt/voldt-api/blob/main/src/lib/loadRoutes.ts"
click node_ai_routes "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_discovery "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_download "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_search "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_tempmail "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_tools "https://github.com/malvolt/voldt-api/tree/main/src/routes"
click node_stats "https://github.com/malvolt/voldt-api/blob/main/src/stats.ts"
click node_stats_file "https://github.com/malvolt/voldt-api/blob/main/public/stats.json"
click node_web "https://github.com/malvolt/voldt-api/tree/main/public"
click node_openapi "https://github.com/malvolt/voldt-api/blob/main/src/app.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_app,node_loader,node_client toneBlue
class node_ai_routes toneAmber
class node_discovery,node_download toneMint
class node_search,node_tempmail,node_tools toneRose
class node_stats,node_stats_file,node_web,node_openapi,node_notegpt,node_mal,node_bing toneIndigo
```

## Components

### API runtime

- [Fastify app](https://github.com/malvolt/voldt-api/blob/main/src/app.ts): `src/app.ts`
- [Route loader](https://github.com/malvolt/voldt-api/blob/main/src/lib/loadRoutes.ts): `src/lib/loadRoutes.ts`

### AI services

- [AI endpoints](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`

### Content services

- [Discovery endpoints](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`
- [Download endpoints](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`

### Search and tools

- [Search endpoints](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`
- [Temporary mail](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`
- [Utility endpoints](https://github.com/malvolt/voldt-api/tree/main/src/routes): `src/routes`

### Stats and web

- [Request counters](https://github.com/malvolt/voldt-api/blob/main/src/stats.ts): `src/stats.ts`
- [Stats file](https://github.com/malvolt/voldt-api/blob/main/public/stats.json): `public/stats.json`
- [Static pages](https://github.com/malvolt/voldt-api/tree/main/public): `public`
- [OpenAPI docs](https://github.com/malvolt/voldt-api/blob/main/src/app.ts): `src/app.ts`

### Other components

- **API client**
- **NoteGPT service**
- **MyAnimeList**
- **Bing Search**

## Connections

- API client → Fastify app: sends requests (evidence: `src/app.ts`)
- Fastify app → Route loader: loads routes (evidence: `src/app.ts`)
- Route loader → AI endpoints: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Route loader → Discovery endpoints: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Route loader → Download endpoints: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Route loader → Search endpoints: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Route loader → Temporary mail: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Route loader → Utility endpoints: imports modules (evidence: `src/lib/loadRoutes.ts`)
- Fastify app → Request counters: updates counters (evidence: `src/app.ts`)
- Request counters → Stats file: reads and writes (evidence: `src/stats.ts`)
- Fastify app → Static pages: serves pages (evidence: `src/app.ts`)
- Fastify app → OpenAPI docs: serves spec (evidence: `src/app.ts`)
- Search endpoints → MyAnimeList: queries details (evidence: `src/routes/search-mal.ts`)
- Search endpoints → Bing Search: fetches results (evidence: `src/routes/search-bing.ts`)
- AI endpoints → NoteGPT service: submits image jobs (evidence: `src/routes/ai-img2img.ts`)
