# number178/kikoeru-express architecture

> Architecture diagram of the GitHub repository number178/kikoeru-express, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/number178/kikoeru-express
- Repository: https://github.com/number178/kikoeru-express

## Overview

##### Overall Project Type and Purpose
- Kikoeru is a full-stack web application that functions as a specialized music streaming server for doujin (同人) audio. It integrates a web front-end (SPA/PWA) with an Express-based backend API.
- Key features include audio metadata scraping from multiple sources, file system scanning for audio libraries, user interaction (e.g., rating, progress marking, tagging), and real-time updates delivered via socket.io. The system also supports deployment via Docker and contains configurable authentication (JWT based) and a lightweight sqlite file database.

##### Main Components
a. User Clients:
- Web Client: Served from the “dist” folder (generated by the kikoeru-quasar SPA/PWA build). This represents the client’s interface (desktop/mobile) which may optionally install a PWA.
- iOS Client: Indicated in the README via TestFlight.

b. API Server:
- Express Application (main entry point “app.js”, “api.js” for wiring routes and JWT middleware) that handles HTTP requests from client apps.
- Routing Modules: Illustrated with the “routes” directory that contains modules for authentication, media handling, reviews, translation, configuration, and several utility routes.
- Middleware & Authentication: Utilizes JWT (from jsonwebtoken) for controlling access, which is wrapped around API endpoints.

c. Database Layer:
- SQLite3 Database: Managed using the “database” folder containing the database initialization, schema definitions (schema.js, storage.js), and numerous migration scripts using knex-migrate.
- Knex & Migration Tools: Indicated by files such as “knexfile.js”, “knex-migrate.js”, and migration scripts in “database/migrations”.

d. Filesystem Scanning & Scraping Modules:
- Filesystem Scanning: The “filesystem” directory hosts code (e.g., scanner.js, updater.js) that scans the audio file libraries. It also includes modules for scanning work files.
- Scraping: The “scraper” directory contains modules (e.g., asmrOne.js, dlsite.js, hvdb.js) using Axios and Cheerio to fetch and parse audio metadata from external sources.

e. Real-time Communication:
- Socket.io: The “socket.js” module initializes socket.io to deliver scanning results or live updates to connected clients.

f. Configuration and Utility Components:
- Configuration Management: “config.js” for reading and updating configuration settings; the “config” folder (mentioned in the README but may not appear in the file tree explicitly) is expected to hold configuration files.
- Common Utilities: “common.js”, “auth/utils.js”, and various helper functions under “routes/utils”.

g. Deployment & Build:
- Docker Support: Presence of Dockerfile, docker-compose.yml, and related scripts (publish_to_docker.sh, build.sh) indicate containerized deployment.
- Build and Linting Tools: Files like .eslintrc.json, package.json (with npm scripts) indicate standardized coding practices and dependency management.

##### Relationships and Interactions
- Client making HTTP calls to the API Server and possibly establishing web-socket connections.
- The API Server should be depicted as mediating between the user’s requests and the database for CRUD operations on audio metadata and reviews.
- The API Server interacts with the filesystem scanner to update the audio library and with the scraper modules to fetch metadata from external sites.
- User Clients → HTTP Requests → Express API (with labeled JWT authentication middleware)
- Express API → Database (using Knex and SQLite via migration scripts)
- Express API ↔ Socket.io Service (for real-time updates)
- Express API → Filesystem Module and Scraper Module (for scanning media folders and fetching external metadata)

##### Architectural Patterns and Design Principles
- Follow the layered architecture separating presentation (frontend SPA/PWA), business logic (Express API with contextual routes), data access (sqlite via knex), and integration (external scraping and file-system scanning).
- Micro-modules (each route and utility placed in separate modules) and the separation of concerns between configuration, filesystem interactions, database operations, and scraping logic.

##### Final Detailed Elements
- “app.js” and “api.js” at the core of the Express layer.
- Cluster the directories: “routes”, “auth”, and “config” modules as part of the API’s business logic.
- “database” folder’s content as the data persistence layer (with knex and migrations).
- Together “filesystem” and “scraper” modules as auxiliary background services that support media metadata processing.
- Deployment scripts (Dockerfile, docker-compose.yml) as a separate block or annotation regarding the deployment environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        WC["Web Client (SPA/PWA from dist)"]:::frontend
        IOS["iOS Client"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        EAS["Express API Server"]:::backend
        subgraph "Entry Points"
            APP["app.js"]:::entrypoint
            API["api.js"]:::entrypoint
        end
        RM["Routing Modules"]:::backend
        JWT["JWT Middleware"]:::middleware
        CU["Config & Utilities"]:::utility
        EAS --> APP
        EAS --> API
        EAS --> RM
        EAS --> JWT
        EAS --> CU
    end

    %% Real-time and Auxiliary Services
    subgraph "Real-time & Auxiliary"
        SIO["Socket.io Service"]:::realtime
        FS["Filesystem Scanner"]:::auxiliary
        SM["Scraper Modules"]:::auxiliary
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        DB["SQLite Database"]:::database
    end

    %% Deployment & Build
    subgraph "Deployment & Build"
        DF["Dockerfile"]:::deployment
        DC["docker-compose.yml"]:::deployment
        BS["build.sh"]:::deployment
        PD["publish_to_docker.sh"]:::deployment
    end

    %% Connections
    WC -->|"HTTP"| EAS
    IOS -->|"HTTP"| EAS

    EAS -->|"CRUD"| DB
    EAS -->|"Triggers"| FS
    EAS -->|"MetadataFetch"| SM
    EAS <==>|"RealTimeUpdates"| SIO

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef entrypoint fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef middleware fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef utility fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef realtime fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef auxiliary fill:#fefefe,stroke:#818182,stroke-width:2px;
    classDef database fill:#f8f9fa,stroke:#ced4da,stroke-width:2px;
    classDef deployment fill:#e2f0cb,stroke:#7bb14b,stroke-width:2px;

    %% Click Events
    click WC "https://github.com/number178/kikoeru-express/tree/alpha/static"
    click APP "https://github.com/number178/kikoeru-express/blob/alpha/app.js"
    click API "https://github.com/number178/kikoeru-express/blob/alpha/api.js"
    click RM "https://github.com/number178/kikoeru-express/tree/alpha/routes"
    click JWT "https://github.com/number178/kikoeru-express/blob/alpha/auth/utils.js"
    click DB "https://github.com/number178/kikoeru-express/tree/alpha/database"
    click FS "https://github.com/number178/kikoeru-express/tree/alpha/filesystem"
    click SM "https://github.com/number178/kikoeru-express/tree/alpha/scraper"
    click SIO "https://github.com/number178/kikoeru-express/blob/alpha/socket.js"
    click CU "https://github.com/number178/kikoeru-express/blob/alpha/config.js"
    click DF "https://github.com/number178/kikoeru-express/tree/alpha/Dockerfile"
    click DC "https://github.com/number178/kikoeru-express/blob/alpha/docker-compose.yml"
    click BS "https://github.com/number178/kikoeru-express/blob/alpha/build.sh"
    click PD "https://github.com/number178/kikoeru-express/blob/alpha/publish_to_docker.sh"
```
