# tachibana-shin/hoyomi architecture

> Architecture diagram of the GitHub repository tachibana-shin/hoyomi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tachibana-shin/hoyomi
- Repository: https://github.com/tachibana-shin/hoyomi

## Overview

##### Project Type and Purpose
- This is a Flutter-based multi-platform mobile/desktop application designed for reading manga and watching anime.
- The README emphasizes free multi-source content and detailed Firebase configuration for authentication.
- In addition to the client app (in /lib, with Android, iOS, Web, Linux, macOS, Windows directories), a separate “serverless” folder contains backend API endpoints (for actions such as “get-watch-time”, user logic and database interactions).

##### File Structure
- Client Application:
- The “lib” directory is extensive, containing pages, controllers, widgets, and services (e.g., comic and eiga services) that implement the UI and core functionalities.
- Platform-specific directories (android, ios, linux, macos, windows, web) include configuration and platform-specific build files.
- Firebase integration is evident via the configuration files (google-services.json, GoogleService-Info.plist) and usage of “flutterfire” CLI commands.
- Serverless Backend:
- The “serverless” directory hosts API endpoints built (e.g., in TypeScript) that likely interact with a Xata database and apply Firebase Admin configuration.
- SQL migrations, Xata configurations, and Drizzle configurations suggest a relational (or SQL-like) backend layered on serverless functions.
- CI/CD:
- The “.github/workflows” directory includes GitHub Actions for analysis, auto-format/fix, and releases, indicating a CI/CD pipeline managing quality and releases.

A. Client Application Component:
- Flutter Mobile/Desktop/Web Client:
- Composed of UI layers (pages, widgets) that include comic reading screens, detail pages, search pages, library views, and more.
- Organized with controllers, mixins, and services (found in the “lib” directory) to handle business logic and API interaction.
- Firebase Integration:
- Handles authentication (Google sign-in) and possibly other real-time or backend services.

B. Serverless Backend Component:
- API Services:
- Contains endpoints (found in serverless/api and related directories) such as “get-watch-time”, “set-watch-time”, etc.
- Written in TypeScript and interacts with business logic and external services.
- Database Service (Xata):
- The serverless folder includes database configurations (e.g., “serverless/db”, “drizzle”, “xata.ts”) indicating the use of the Xata database along with migrations.
- Firebase Admin Integration:
- Uses Firebase Admin (configured via service-account-key.json) for secure server-side operations.

C. CI/CD and Build Infrastructure:
- GitHub Workflows:
- Automated pipelines (analysis, formatting, releasing) that bundle with the repository.
- Shown as separate tooling that ties in with both client and serverless deployments.

##### Relationships and Interactions
- User Flow:
- End users interact with the Flutter client app.
- The client sends requests (API calls) to the serverless backend endpoints.
- The serverless backend processes requests, interacts with the Xata database, and may also perform server-side Firebase Admin operations.
- Data Flow:
- CI/CD:

##### Architectural Patterns and Design Principles
- Multi-Tiered Architecture:
- Clear separation between the client (UI/UX, business logic) and the backend (API processing, database interactions).
- Modular Design:
- The directory structure (pages, widgets, controllers in “lib”) demonstrates modularity in the client.
- The “serverless” folder’s separation into API, database, and logic further stresses modular backend design.
- Dependency Injection and Reusable Services:
- Use of “composable” elements and services likely align with best practices for dependency injection and code reuse.
- Cross-Platform Support:
- The existence of multiple platform-specific directories (Android, iOS, etc.) signifies careful planning for cross-platform compatibility.

##### Instructing the Principal Software Engineer
- Be very detailed: capture all essential architectural elements such as API endpoints in “serverless”, the multiple configuration files in the mobile project (Firebase, OAuth, etc.), and the CI/CD pipelines.
- Additionally annotating these components with key technologies and tools (e.g., Flutter for UI, Firebase for authentication, Xata with Drizzle for the database, GitHub Actions for CI/CD).

– A multi-platform Flutter client with components (pages, widgets, services, controllers), integrated with Firebase for authentication.
– A serverless backend containing API endpoints that handle anime and manga content requests, which interface with a Xata-managed database and use Firebase Admin for secure operations.
– CI/CD pipelines ensuring code quality and automated deployments.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    User["User"]

    %% Flutter Client Subgraph
    subgraph "Flutter Client"
        ClientLib["Flutter Client (/lib)"]
        
        subgraph "Platform Configurations"
            AndroidConfig["Android Config (Android)"]
            iOSConfig["iOS Config (iOS)"]
            LinuxConfig["Linux Config (Linux)"]
            MacosConfig["macOS Config (macOS)"]
            WindowsConfig["Windows Config (Windows)"]
            WebConfig["Web Config (Web)"]
        end

        FirebaseOptions["Firebase Options (/lib/firebase_options.dart)"]
        AndroidFirebase["Android Firebase Config (/android/app)"]
    end

    %% Serverless Backend Subgraph
    subgraph "Serverless Backend"
        APIEndpoints["API Endpoints (/serverless/api)"]
        Logic["Business Logic (/serverless/logic)"]
        Services["Services (/serverless/services)"]
        FirebaseAdmin["Firebase Admin (/serverless/firebase-admin.ts)"]
        
        subgraph "Database Service"
            DBConfig["DB Config (/serverless/db)"]
            SQLMigrations["SQL Migrations (/serverless/drizzle)"]
            XataConfig["Xata Config (/serverless/xata.ts)"]
        end
    end

    %% CI/CD Pipeline
    CICD["CI/CD Pipeline (/github/workflows)"]

    %% Relationships
    User -->|"uses"| ClientLib
    ClientLib -->|"authenticates_with"| FirebaseOptions
    ClientLib -->|"uses"| AndroidFirebase
    ClientLib -->|"calls"| APIEndpoints
    APIEndpoints -->|"delegates_to"| Logic
    APIEndpoints -->|"delegates_to"| Services
    Logic -->|"queries"| DBConfig
    Services -->|"queries"| DBConfig
    Logic -->|"calls"| FirebaseAdmin
    Services -->|"calls"| FirebaseAdmin
    CICD -->|"builds"| ClientLib
    CICD -->|"deploys"| APIEndpoints

    %% Click Events
    click ClientLib "https://github.com/tachibana-shin/hoyomi/tree/main//lib"
    click AndroidConfig "https://github.com/tachibana-shin/hoyomi/tree/main//android"
    click iOSConfig "https://github.com/tachibana-shin/hoyomi/tree/main//ios"
    click LinuxConfig "https://github.com/tachibana-shin/hoyomi/tree/main//linux"
    click MacosConfig "https://github.com/tachibana-shin/hoyomi/tree/main//macos"
    click WindowsConfig "https://github.com/tachibana-shin/hoyomi/tree/main//windows"
    click WebConfig "https://github.com/tachibana-shin/hoyomi/tree/main//web"
    click FirebaseOptions "https://github.com/tachibana-shin/hoyomi/blob/main//lib/firebase_options.dart"
    click AndroidFirebase "https://github.com/tachibana-shin/hoyomi/tree/main//android/app"
    click APIEndpoints "https://github.com/tachibana-shin/hoyomi/tree/main//serverless/api"
    click Logic "https://github.com/tachibana-shin/hoyomi/tree/main//serverless/logic"
    click Services "https://github.com/tachibana-shin/hoyomi/tree/main//serverless/services"
    click FirebaseAdmin "https://github.com/tachibana-shin/hoyomi/blob/main//serverless/firebase-admin.ts"
    click DBConfig "https://github.com/tachibana-shin/hoyomi/tree/main//serverless/db"
    click SQLMigrations "https://github.com/tachibana-shin/hoyomi/tree/main//serverless/drizzle"
    click XataConfig "https://github.com/tachibana-shin/hoyomi/blob/main//serverless/xata.ts"
    click CICD "https://github.com/tachibana-shin/hoyomi/tree/main//github/workflows"

    %% Styles
    class ClientLib,AndroidConfig,iOSConfig,LinuxConfig,MacosConfig,WindowsConfig,WebConfig UserStyle
    class ClientLib,AndroidConfig,iOSConfig,LinuxConfig,MacosConfig,WindowsConfig,WebConfig client
    class FirebaseOptions,AndroidFirebase firebase
    class APIEndpoints,Logic,Services,FirebaseAdmin backend
    class DBConfig,SQLMigrations,XataConfig database
    class CICD infra

    %% Class Definitions
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef infra fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef firebase fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
```
