How number178/kikoeru-express works
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.