# bulatenkom/manga-updater architecture

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

- Interactive diagram: https://gitdiagram.com/bulatenkom/manga-updater
- Repository: https://github.com/bulatenkom/manga-updater

## Overview

##### Project type and purpose
- This is a full‑stack web application consisting of:
- A Python‑based asynchronous REST API server (“manga‑updater” backend) that scrapes external manga sites, maintains application state, schedules tasks, and provides data over HTTP.
- A Vue3 & Quasar SPA client that consumes the API to display manga lists, detail pages, and chapter content.

##### File structure
- Top‑level directories:
- backend/ – REST server code, parsers, models, async event loop, persistence, requirements.
- frontend/ – Web UI built with Vue3, Quasar, Vite, organized into components, pages, router, store, assets.
- doc/ – documentation and screenshots.
- Key backend modules:
- main.py – entrypoint for FastAPI/uvicorn.
- async.py, parsers.py – event‑loop orchestration and site‑specific scraping logic.
- db.py – persistence layer (disk‑backed state).
- models.py, msgspec_hooks.py – data schemas and serialization hooks.
- utils.py, exceptions.py – shared helpers.
- Frontend structure follows typical SPA pattern:
- src/router – route definitions.
- src/store – global state management.
- src/pages & src/components – views and reusable UI.
- Quasar config, assets, env declarations, CSS.

##### README for additional insights
- Backend uses FastAPI, uvicorn, asyncio, BeautifulSoup4, msgspec, structlog, rich.
- Core features: scraper tasks, state save/load (manga_list, monitoring_list, download_deque, task_queue), next‑chapter estimation.
- Client uses Vue-router, Quasar CLI/Vite.
- Development uses a CORS proxy for local testing, separate “dev.sh” to launch server on port 8000 and proxy on 7777.

##### Essential architectural elements
- Event‑loop and task‑queue are visible, because the core of this app is asynchronous scraping and scheduling.
- Boundary between front‑end and back‑end.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User("User (Browser)"):::external

    %% Frontend Zone
    subgraph "Frontend (Browser)" 
        direction TB
        SPA_Root["Client SPA Root"]:::frontend
        QuasarCfg["Quasar Configuration"]:::frontend
        HTTPClient["HTTP Client Module (api.ts)"]:::frontend
        RouterIdx["Router Definitions"]:::frontend
        StoreGH["Global State Management"]:::frontend
        Pages["Application Pages"]:::frontend
        Components["Reusable UI Components"]:::frontend
        Layouts["Application Layouts"]:::frontend
        Assets["Static Assets & Icons"]:::frontend
        Styles["Global Styles & CSS"]:::frontend
        Boot["Boot Files"]:::frontend
    end

    %% Backend Zone
    subgraph "Backend (Server)" 
        direction TB
        APIServer["REST API Server (FastAPI/Uvicorn)"]:::backend
        EventLoop["Async Event Loop & Scheduler"]:::backend
        ParserMod["Site-Specific Scraping Logic"]:::backend
        Persistence["Persistence Layer (disk-backed state)"]:::datastore
        Models["Data Schemas & Models"]:::backend
        MsgspecHooks["Msgspec Serialization Hooks"]:::backend
        Utils["Shared Utilities & Helpers"]:::backend
        Exceptions["Exception Definitions"]:::backend
        ReqSpecs["Backend Dependencies (requirements.txt)"]:::backend
    end

    %% External Systems
    ExternalSites("External Manga Sites"):::external
    CORSProxy("CORS Proxy (Dev Only)"):::external

    %% Connections
    User -->|"interacts with"| SPA_Root
    SPA_Root --> QuasarCfg
    SPA_Root --> RouterIdx
    SPA_Root --> StoreGH
    SPA_Root --> Pages
    SPA_Root --> Components
    SPA_Root --> Layouts
    SPA_Root --> Assets
    SPA_Root --> Styles
    SPA_Root --> Boot

    Pages --> HTTPClient
    HTTPClient -->|HTTP Requests| APIServer
    HTTPClient -->|HTTP Requests via Proxy| CORSProxy
    CORSProxy -->|HTTP Requests| APIServer

    APIServer --> Models
    APIServer --> Utils
    APIServer --> Exceptions
    APIServer --> MsgspecHooks
    APIServer --> Persistence
    APIServer --> EventLoop

    EventLoop -->|schedules tasks| ParserMod
    ParserMod -->|scrapes| ExternalSites
    EventLoop -->|enqueue download tasks| Persistence

    %% Click Events Frontend
    click SPA_Root "https://github.com/bulatenkom/manga-updater/tree/master/frontend/"
    click QuasarCfg "https://github.com/bulatenkom/manga-updater/blob/master/frontend/quasar.config.ts"
    click HTTPClient "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/api/api.ts"
    click RouterIdx "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/router/index.ts"
    click StoreGH "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/store/store.ts"
    click Pages "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/pages/IndexPage.vue"
    click Components "https://github.com/bulatenkom/manga-updater/tree/master/frontend/src/components/"
    click Layouts "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/layouts/RootLayout.vue"
    click Assets "https://github.com/bulatenkom/manga-updater/tree/master/frontend/src/assets/"
    click Styles "https://github.com/bulatenkom/manga-updater/blob/master/frontend/src/css/app.scss"
    click Boot "https://github.com/bulatenkom/manga-updater/tree/master/frontend/src/boot/"

    %% Click Events Backend
    click APIServer "https://github.com/bulatenkom/manga-updater/blob/master/backend/main.py"
    click EventLoop "https://github.com/bulatenkom/manga-updater/blob/master/backend/async.py"
    click ParserMod "https://github.com/bulatenkom/manga-updater/blob/master/backend/parsers.py"
    click Persistence "https://github.com/bulatenkom/manga-updater/blob/master/backend/db.py"
    click Models "https://github.com/bulatenkom/manga-updater/blob/master/backend/models.py"
    click MsgspecHooks "https://github.com/bulatenkom/manga-updater/blob/master/backend/msgspec_hooks.py"
    click Utils "https://github.com/bulatenkom/manga-updater/blob/master/backend/utils.py"
    click Exceptions "https://github.com/bulatenkom/manga-updater/blob/master/backend/exceptions.py"
    click ReqSpecs "https://github.com/bulatenkom/manga-updater/blob/master/backend/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#037DD6,color:#000
    classDef backend fill:#D6F5D6,stroke:#14961A,color:#000
    classDef external fill:#FFF4C1,stroke:#D9A600,color:#000
    classDef datastore fill:#E0E0E0,stroke:#7A7A7A,color:#000
```
