# tsukasa-u/fusou architecture

> Architecture diagram of the GitHub repository tsukasa-u/fusou, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsukasa-u/fusou
- Repository: https://github.com/tsukasa-u/fusou

## Overview

##### Project type and purpose
- This is a polyglot monorepo combining:
- FUSOU-PROXY (Rust-based HTTP/HTTPS proxy services)
- FUSOU-APP (Tauri desktop application using Rust + TypeScript/React)
- FUSOU-WEB (Astro-based web frontend with React/Solid and Supabase/duckDB backend)
- shared-ui (UI component library)
- Purpose:
- Intercept KanColle game HTTP traffic via local proxy
- Parse and expose in-game data in a Tauri desktop viewer
- Optionally upload or sync parsed data to a Supabase-powered online store
- Provide an online portal for exploring aggregated/analyzed data

##### High-level file-structure analysis
- Top-level directories:
- packages/FUSOU-PROXY – Rust crates for proxy-http and proxy-https
- packages/FUSOU-APP – Tauri front-end (TypeScript/React + Rust CLI & library crates)
- packages/FUSOU-WEB – Static/Astro site with serverless API routes (Supabase auth)
- packages/shared-ui – Storybook and reusable UI components
- FUSOU-APP substructure:
- kc_api – Rust library for parsing KanColle API JSON → tables → interfaces
- register_macro_derive_and_attr & register_trait – Rust proc-macro crates for code generation
- src-tauri – Tauri wrapper & system-level commands (proxy control, Google Drive, Discord, Supabase)
- src – React/TypeScript UI components, pages, Tailwind CSS, Vite config
- FUSOU-WEB substructure:
- Astro configuration, serverless API routes for authentication & data access
- React/Solid chart components, duckDB in-browser, Google Drive integration

##### Key insights from README
- System is split into local (“in-game viewer”) vs. online (“analyzed data viewer”)
- FUSOU-PROXY relays/records HTTP(S) traffic through a proxy server
- FUSOU-APP is the minimal desktop viewer (Tauri)
- FUSOU-WEB is the web portal for aggregated/analyzed data
- Future plan: collect data from many users, run analytics

##### Main components
a. Components:
- Game Client (KanColle browser or DMM client)
- Local Proxy Servers (HTTP & HTTPS)
- Tauri Desktop App:
– kc_api Rust library (parsing & database layer)
– register_macro_derive_and_attr & register_trait (proc-macros)
– Tauri runtime (Rust + TypeScript/React UI)
– Local storage (e.g., SQLite or local file)
– Optional upload service (Supabase client)
- Online Service:
– Supabase Authentication & Database
– Serverless API Routes (Astro)
– Web Frontend (Astro + React/Solid)
– In-browser duckDB & Google Drive integration
- shared-ui library (used by both app & web)

b. Relationships & data flows:
1. Game Client → (configured to use) → Local Proxy (HTTP/HTTPS)
2. Proxy → forwards requests to KanColle servers, logs JSON responses
3. Tauri App → reads from Proxy or watches local proxy log port
4. kc_api → parses JSON → domain structs → stores in local DB
5. Desktop UI → reads from local DB → renders tables/charts
6. Desktop App → (optionally) → Supabase client → pushes selected data
7. Web Frontend → Supabase auth → fetches aggregated data → renders charts
8. Web → optional in-browser duckDB for client-side analytics
9. Google Drive integration for additional storage/backup

c. Architectural patterns & principles:
- Hexagonal/Clean architecture in Rust kc_api (database vs. interface vs. core)
- Proc-macro crates for code generation (DRY & maintainable interface definitions)
- Micro-frontend separation: local app vs. web portal
- Serverless functions for auth & data endpoints (Astro + Supabase)
- Shared component library (shared-ui) for consistent design

d. Key technologies & frameworks:
- Rust & Cargo (kc_api, proxy servers, proc-macros, Tauri backend)
- Tauri (desktop shell → Rust + TypeScript bridge)
- TypeScript + React + Vite + Tailwind CSS (desktop UI)
- Astro + React + Solid (web portal)
- Supabase (auth, real-time DB)
- duckDB (in-browser SQL analytics)
- Google Drive API (backup/export)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Local Tier
  subgraph "Local Tier"
    direction TB
    GameClient["Game Client (KanColle)"]:::external
    subgraph "Proxy Servers"
      direction TB
      HTTPProxy["Local HTTP Proxy Server"]:::rust
      HTTPSProxy["Local HTTPS Proxy Server"]:::rust
    end
    GameClient -->|"HTTP traffic"| HTTPProxy
    GameClient -->|"HTTPS traffic"| HTTPSProxy
  end

  %% Desktop Tier
  subgraph "Desktop App Tier"
    direction TB
    subgraph "Codegen (Rust Proc-Macros)" 
      direction TB
      ProcDerive["register_macro_derive_and_attr"]:::rust
      ProcTrait["register_trait"]:::rust
    end
    ProcDerive -->|"generates code for"| kcAPI
    ProcTrait -->|"generates code for"| kcAPI

    kcAPI["kc_api (Rust/Cargo)"]:::rust
    kcAPI -->|"parsed data"| LocalDB

    subgraph "Tauri Runtime & UI"
      direction TB
      TauriBackend["Tauri Desktop App – Rust Backend & Commands"]:::rust
      DesktopUI["Tauri Desktop App – TypeScript/React UI"]:::ts
    end
    HTTPProxy -->|"logs JSON responses"| TauriBackend
    HTTPSProxy -->|"logs JSON responses"| TauriBackend
    TauriBackend -->|"calls parsing lib"| kcAPI
    TauriBackend -->|"serves UI"| DesktopUI
    DesktopUI -->|"reads from"| LocalDB
    LocalDB["Local Storage (SQLite)"]:::db
    TauriBackend -->|"optional push"| SupabaseSync

    SupabaseSync["Supabase Sync Client"]:::ts
    TauriBackend -->|"uses"| SupabaseSync
  end

  %% Shared UI
  SharedUI["shared-ui (Storybook UI Components)"]:::shared
  DesktopUI -->|"dependency"| SharedUI

  %% Web Tier
  subgraph "Web Tier"
    direction TB
    AstroConfig["Web Portal – Astro Configuration"]:::ts
    APIRoutes["Serverless API Routes"]:::purple
    SupabaseDB["Supabase Auth & Database"]:::db
    WebUI["Web Frontend (Astro + React/Solid)"]:::ts
    ReactComponents["React Components"]:::ts
    SolidComponents["Solid Components"]:::ts
    DuckDB["In-Browser duckDB Analytics"]:::purple
    GoogleDrive["Google Drive Integration"]:::purple
    WebSupabaseClient["Supabase Client Library"]:::ts
    PageLayouts["Page Layouts & Public Pages"]:::ts
    WebUtility["Shared Utility for Web (supabase/session)"]:::ts

    AstroConfig -->|"configures"| APIRoutes
    APIRoutes -->|"auth & data access"| SupabaseDB
    WebUI -->|"calls API routes"| APIRoutes
    WebUI -->|"renders UI using"| ReactComponents
    WebUI -->|"renders UI using"| SolidComponents
    WebUI -->|"client analytics"| DuckDB
    WebUI -->|"backup/backup"| GoogleDrive
    WebUI -->|"uses session state"| WebUtility
    WebUI -->|"uses"| WebSupabaseClient
    WebUI -->|"uses common UI"| SharedUI
  end

  %% External Cloud
  SupabaseDB -->|"cloud service"| CloudSupabase["Supabase Cloud"]:::cloud
  GoogleDrive -->|"external storage"| CloudDrive["Google Drive"]:::cloud

  %% Relationships between tiers
  SupabaseSync -->|"push data to"| CloudSupabase
  CloudSupabase -->|"aggregated data"| APIRoutes

  %% Click Events
  click HTTPProxy "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-PROXY/proxy-http"
  click HTTPSProxy "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-PROXY/proxy-https"
  click TauriBackend "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-APP/src-tauri"
  click DesktopUI "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-APP/src"
  click kcAPI "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-APP/kc_api"
  click ProcDerive "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-APP/register_macro_derive_and_attr"
  click ProcTrait "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-APP/register_trait"
  click SupabaseSync "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-APP/src-tauri/src/supabase.rs"
  click SharedUI "https://github.com/tsukasa-u/fusou/tree/main/packages/shared-ui"
  click AstroConfig "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/astro.config.mjs"
  click APIRoutes "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-WEB/src/pages/api"
  click ReactComponents "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-WEB/src/components/react"
  click SolidComponents "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-WEB/src/components/solid"
  click DuckDB "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/src/db/duckDB.tsx"
  click GoogleDrive "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/src/db/googleDrive.ts"
  click WebSupabaseClient "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/src/lib/supabase.ts"
  click PageLayouts "https://github.com/tsukasa-u/fusou/tree/main/packages/FUSOU-WEB/src/pages"
  click PageLayouts "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/src/layouts/Layout.astro"
  click WebUtility "https://github.com/tsukasa-u/fusou/blob/main/packages/FUSOU-WEB/src/utility/supabase.ts"

  %% Styles
  classDef rust fill:#E44D26,stroke:#000,stroke-width:1px,color:#fff
  classDef ts fill:#3178C6,stroke:#000,stroke-width:1px,color:#fff
  classDef purple fill:#9C27B0,stroke:#000,stroke-width:1px,color:#fff
  classDef db fill:#FFC107,stroke:#000,stroke-width:1px,color:#000
  classDef cloud fill:#90A4AE,stroke:#000,stroke-width:1px,color:#fff
  classDef shared fill:#4CAF50,stroke:#000,stroke-width:1px,color:#fff
  classDef external fill:#607D8B,stroke:#000,stroke-width:1px,color:#fff
```
