# mcalec-dev/gdl-api architecture

> Architecture diagram of the GitHub repository mcalec-dev/gdl-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/mcalec-dev/gdl-api
- Repository: https://github.com/mcalec-dev/gdl-api

## Overview

gdl-api is an Express-backed gallery-dl file library: users browse and retrieve files, search the indexed collection, and can upload content; accounts, pools, statistics, and administration provide supporting product capabilities. The graph emphasizes API routing, filesystem indexing and metadata, search, and persistence, while retaining the documented UI and other major API branches. Several route implementations are not sampled, so links to their underlying behavior are omitted where evidence is unavailable.

Main entry points: [`routes/api/index.js`](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/index.js) (API router), [`server.js`](https://github.com/mcalec-dev/gdl-api/blob/main/server.js) (Express server), [`utils/file/upsert.js`](https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/upsert.js) (File indexing), [`utils/search/repository.js`](https://github.com/mcalec-dev/gdl-api/blob/main/utils/search/repository.js) (Search repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_server["Express server<br/>[server.js]"]
  node_api["API router<br/>[index.js]"]
  node_webui["Browser interface<br/>[index.js]"]
  node_auth["Authentication"]
  node_userapi["User account API"]
  node_admin["Administration"]
end

subgraph group_library["File library"]
  node_filesapi["File API<br/>[files.js]"]
  node_filesystem[("Collection filesystem")]
  node_listing["Directory listing<br/>[listing.js]"]
  node_sync["Filesystem sync<br/>[sync.js]"]
  node_upsert["File indexing<br/>[upsert.js]"]
  node_metadata["Media metadata<br/>[metadata.js]"]
  node_media["Media processing<br/>[resize.js]"]
  node_download["Download API<br/>[download.js]"]
  node_upload["Upload API<br/>[upload.js]"]
end

subgraph group_data["Persistence and indexing"]
  node_searchrepo["Search repository<br/>[repository.js]"]
  node_filemodel[("File records<br/>[File.js]")]
  node_directorymodel[("Directory records<br/>[Directory.js]")]
  node_gridfs[("Uploaded file store<br/>[gridfsUtils.js]")]
  node_redis[("Redis cache<br/>[redisClient.js]")]
  node_statsmodel["Statistics snapshots<br/>[snapshot.js]"]
  node_sessions["Session storage<br/>[sessionStore.js]"]
end

subgraph group_features["Library features"]
  node_searchapi["Search API<br/>[search.js]"]
  node_search["Search engine<br/>[searchDatabase.js]"]
  node_pools["Pools<br/>[pool.js]"]
  node_random["Random files<br/>[random.js]"]
  node_stats["Statistics<br/>[stats.js]"]
  node_announcements["Announcements<br/>[announcements.js]"]
  node_health["Health check<br/>[health.js]"]
end

node_user(("Gallery user"))
node_mongo[("MongoDB")]

node_user -->|"uses"| node_webui
node_server -->|"mounts routes"| node_api
node_server -->|"renders pages"| node_webui
node_api -->|"mounts"| node_auth
node_api -->|"mounts"| node_userapi
node_api -->|"mounts"| node_admin
node_api -->|"mounts"| node_filesapi
node_api -->|"mounts"| node_download
node_api -->|"mounts"| node_upload
node_api -->|"mounts"| node_searchapi
node_api -->|"mounts"| node_pools
node_api -->|"mounts"| node_random
node_api -->|"mounts"| node_stats
node_api -->|"mounts"| node_announcements
node_api -->|"mounts"| node_health
node_filesapi -.->|"uses"| node_listing
node_listing -.->|"reads"| node_filesystem
node_sync -->|"scans"| node_filesystem
node_sync -->|"indexes entries"| node_upsert
node_upsert -->|"writes"| node_filemodel
node_upsert -->|"writes"| node_directorymodel
node_upsert -->|"gets metadata"| node_metadata
node_searchapi -->|"invokes"| node_search
node_search -->|"fetches results"| node_searchrepo
node_searchrepo -->|"queries"| node_filemodel
node_searchrepo -->|"queries"| node_directorymodel
node_upload -.->|"stores content"| node_gridfs
node_gridfs -.->|"persists"| node_mongo
node_server -->|"connects"| node_mongo
node_server -->|"initializes"| node_sessions
node_sessions -->|"uses when available"| node_redis
node_sessions -->|"falls back to"| node_mongo
node_server -->|"initializes cache"| node_redis
node_stats -.->|"uses snapshots"| node_statsmodel
node_statsmodel -.->|"reads listing data"| node_filemodel

click node_server "https://github.com/mcalec-dev/gdl-api/blob/main/server.js"
click node_api "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/index.js"
click node_webui "https://github.com/mcalec-dev/gdl-api/blob/main/public/js/index.js"
click node_auth "https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/auth"
click node_userapi "https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/user"
click node_admin "https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/admin"
click node_filesapi "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/files.js"
click node_listing "https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/listing.js"
click node_sync "https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/sync.js"
click node_upsert "https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/upsert.js"
click node_metadata "https://github.com/mcalec-dev/gdl-api/blob/main/utils/image/metadata.js"
click node_media "https://github.com/mcalec-dev/gdl-api/blob/main/utils/image/resize.js"
click node_download "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/download.js"
click node_upload "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/upload.js"
click node_searchapi "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/search.js"
click node_search "https://github.com/mcalec-dev/gdl-api/blob/main/utils/search/searchDatabase.js"
click node_searchrepo "https://github.com/mcalec-dev/gdl-api/blob/main/utils/search/repository.js"
click node_filemodel "https://github.com/mcalec-dev/gdl-api/blob/main/models/File.js"
click node_directorymodel "https://github.com/mcalec-dev/gdl-api/blob/main/models/Directory.js"
click node_gridfs "https://github.com/mcalec-dev/gdl-api/blob/main/utils/gridfsUtils.js"
click node_redis "https://github.com/mcalec-dev/gdl-api/blob/main/utils/db/redisClient.js"
click node_pools "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/pool.js"
click node_random "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/random.js"
click node_stats "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/stats.js"
click node_statsmodel "https://github.com/mcalec-dev/gdl-api/blob/main/utils/stats/snapshot.js"
click node_announcements "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/user/announcements.js"
click node_health "https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/health.js"
click node_sessions "https://github.com/mcalec-dev/gdl-api/blob/main/utils/sessionStore.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_server,node_api,node_webui,node_auth,node_userapi,node_admin,node_user toneBlue
class node_filesapi,node_filesystem,node_listing,node_sync,node_upsert,node_metadata,node_media,node_download,node_upload,node_mongo toneAmber
class node_searchrepo,node_filemodel,node_directorymodel,node_gridfs,node_redis,node_statsmodel,node_sessions toneMint
class node_searchapi,node_search,node_pools,node_random,node_stats,node_announcements,node_health toneRose
```

## Components

### Web application

- [Express server](https://github.com/mcalec-dev/gdl-api/blob/main/server.js): `server.js`
- [API router](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/index.js): `routes/api/index.js`
- [Browser interface](https://github.com/mcalec-dev/gdl-api/blob/main/public/js/index.js): `public/js/index.js`
- [Authentication](https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/auth): `routes/api/auth`
- [User account API](https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/user): `routes/api/user`
- [Administration](https://github.com/mcalec-dev/gdl-api/tree/main/routes/api/admin): `routes/api/admin`

### File library

- [File API](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/files.js): `routes/api/files.js`
- **Collection filesystem**
- [Directory listing](https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/listing.js): `utils/file/listing.js`
- [Filesystem sync](https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/sync.js): `utils/file/sync.js`
- [File indexing](https://github.com/mcalec-dev/gdl-api/blob/main/utils/file/upsert.js): `utils/file/upsert.js`
- [Media metadata](https://github.com/mcalec-dev/gdl-api/blob/main/utils/image/metadata.js): `utils/image/metadata.js`
- [Media processing](https://github.com/mcalec-dev/gdl-api/blob/main/utils/image/resize.js): `utils/image/resize.js`
- [Download API](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/download.js): `routes/api/download.js`
- [Upload API](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/upload.js): `routes/api/upload.js`

### Persistence and indexing

- [Search repository](https://github.com/mcalec-dev/gdl-api/blob/main/utils/search/repository.js): `utils/search/repository.js`
- [File records](https://github.com/mcalec-dev/gdl-api/blob/main/models/File.js): `models/File.js`
- [Directory records](https://github.com/mcalec-dev/gdl-api/blob/main/models/Directory.js): `models/Directory.js`
- [Uploaded file store](https://github.com/mcalec-dev/gdl-api/blob/main/utils/gridfsUtils.js): `utils/gridfsUtils.js`
- [Redis cache](https://github.com/mcalec-dev/gdl-api/blob/main/utils/db/redisClient.js): `utils/db/redisClient.js`
- [Statistics snapshots](https://github.com/mcalec-dev/gdl-api/blob/main/utils/stats/snapshot.js): `utils/stats/snapshot.js`
- [Session storage](https://github.com/mcalec-dev/gdl-api/blob/main/utils/sessionStore.js): `utils/sessionStore.js`

### Library features

- [Search API](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/search.js): `routes/api/search.js`
- [Search engine](https://github.com/mcalec-dev/gdl-api/blob/main/utils/search/searchDatabase.js): `utils/search/searchDatabase.js`
- [Pools](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/pool.js): `routes/api/pool.js`
- [Random files](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/random.js): `routes/api/random.js`
- [Statistics](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/stats.js): `routes/api/stats.js`
- [Announcements](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/user/announcements.js): `routes/api/user/announcements.js`
- [Health check](https://github.com/mcalec-dev/gdl-api/blob/main/routes/api/health.js): `routes/api/health.js`

### Other components

- **Gallery user**
- **MongoDB**

## Connections

- Gallery user → Browser interface: uses
- Express server → API router: mounts routes (evidence: `server.js`)
- Express server → Browser interface: renders pages (evidence: `server.js`)
- API router → Authentication: mounts (evidence: `routes/api/index.js`)
- API router → User account API: mounts (evidence: `routes/api/index.js`)
- API router → Administration: mounts (evidence: `routes/api/index.js`)
- API router → File API: mounts (evidence: `routes/api/index.js`)
- API router → Download API: mounts (evidence: `routes/api/index.js`)
- API router → Upload API: mounts (evidence: `routes/api/index.js`)
- API router → Search API: mounts (evidence: `routes/api/index.js`)
- API router → Pools: mounts (evidence: `routes/api/index.js`)
- API router → Random files: mounts (evidence: `routes/api/index.js`)
- API router → Statistics: mounts (evidence: `routes/api/index.js`)
- API router → Announcements: mounts (evidence: `routes/api/index.js`)
- API router → Health check: mounts (evidence: `routes/api/index.js`)
- File API → Directory listing: uses
- Directory listing → Collection filesystem: reads
- Filesystem sync → Collection filesystem: scans (evidence: `utils/file/sync.js`)
- Filesystem sync → File indexing: indexes entries (evidence: `utils/file/sync.js`)
- File indexing → File records: writes (evidence: `utils/file/upsert.js`)
- File indexing → Directory records: writes (evidence: `utils/file/upsert.js`)
- File indexing → Media metadata: gets metadata (evidence: `utils/file/upsert.js`)
- Search API → Search engine: invokes (evidence: `routes/api/search.js`)
- Search engine → Search repository: fetches results (evidence: `utils/search/searchDatabase.js`)
- Search repository → File records: queries (evidence: `utils/search/repository.js`)
- Search repository → Directory records: queries (evidence: `utils/search/repository.js`)
- Upload API → Uploaded file store: stores content
- Uploaded file store → MongoDB: persists
- Express server → MongoDB: connects (evidence: `server.js`)
- Express server → Session storage: initializes (evidence: `server.js`)
- Session storage → Redis cache: uses when available (evidence: `utils/sessionStore.js`)
- Session storage → MongoDB: falls back to (evidence: `utils/sessionStore.js`)
- Express server → Redis cache: initializes cache (evidence: `server.js`)
- Statistics → Statistics snapshots: uses snapshots
- Statistics snapshots → File records: reads listing data
