# team-phitogether/phitogether architecture

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

- Interactive diagram: https://gitdiagram.com/team-phitogether/phitogether
- Repository: https://github.com/team-phitogether/phitogether

## Overview

##### Project Type and Purpose
- PhiTogether is a *cross-platform*, *frontend-centric* rhythm game built on a modern web stack (Vue + Vite), wrapped into native Android/iOS shells via Capacitor.
- It delivers a PWA on the web and uses static hosting for game assets (charts, audio, video), plus integrates with external “PhiZone” (and Taptap) community APIs for multiplayer features.

##### File Structure Analysis
- Top-level:
- **package.json**, **vite.config.js**, **tsconfig.json** → Node/Vite build for web.
- **android/** and **ios/** → Capacitor native wrappers and platform-specific code.
- **public/** → Static assets served at runtime: manifest, service worker, chart/audio/video files, versioning API endpoints.
- **src/** → Vue application source: components, pages (.vue), router, utilities, WebAssembly and IndexedDB wrappers (ptdb).
- **script/** → Custom build scripts and utilities (build.js, checki18n.js).
- Patterns & Configurations:
- Vue + Vue-Router for SPA pages (in `src/components/pages` + `src/components/router`).
- IndexedDB abstraction (`src/components/ptdb`) for local persistence of charts and user data.
- WASM module (`pzEncrypted.wasm`) used for decryption / performance-critical logic.
- Capacitor config (`capacitor.config.json`) bridges the webview to native filesystem, permissions, plugins.

##### README Insights
- Open-source, community-driven, licensed under AGPL-3.0.
- Emphasis on multiplayer (“PhiZone integrated”) and non-commercial use.
- No bespoke backend server in repo—relies on static JSON+multimedia + external APIs.

a. Main Components
1. **Frontend/Web Application**
– Vue3 SPA (components, pages, router)
– Renderer core (sim-phi engine + plugins)
– WebAssembly decryption module
2. **Native Shells**
– Android wrapper (Java/Kotlin + Capacitor bridge)
– iOS wrapper (Swift + Capacitor bridge)
3. **Static Asset Server (CDN/Hosting)**
– Serves `public/` folder: chart JSON, audio/video, JS bundles, service worker, `api/*` endpoints for versioning
4. **External Community APIs**
– PhiZone (user profiles, lobbies)
– Taptap API integration
5. **Client-side Storage**
– IndexedDB (ptdb ObjectStores for charts, userData, skins, caches)
– Local filesystem via Capacitor (for media caching, replays, recordings)

b. Relationships & Data Flows
- Web App ←→ Static Asset Server (HTTP GET for JS, CSS, charts, audio/video)
- Web App ←→ External APIs (PhiZone, Taptap REST calls)
- Web App → IndexedDB (store/load chart data, user settings)
- Web App → WASM Module (in-browser decryption/processing)
- Web App ↔ Native Shell (Capacitor bridge for file access, device APIs)

c. Architectural Patterns & Principles
– **MVVM/SPAs**: Vue components separated into UI (pages) and services (utils, api wrappers).
– **Modular Renderer**: sim-phi engine with plugin architecture (SpecialChartsProcessor, video-recorder).
– **Offline-First**: Service worker (`sw.v2.1.js`), IndexedDB caching.
– **Cross-Platform**: Single codebase deployed to Web, Android, iOS.

d. Key Technologies
– Vue3 + Vue-Router + Vite
– TypeScript + JavaScript modules
– Capacitor (Android / iOS native bridge)
– IndexedDB (`ptdb` wrappers)
– WebAssembly (`pzEncrypted.wasm`)
– Service Worker (PWA caching)
– External REST APIs (PhiZone, Taptap)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Frontend/Web Application"
    direction TB
    Pages["SPA Pages"]:::ui
    click Pages "https://github.com/team-phitogether/phitogether/tree/main/src/components/pages/"
    Router["Router"]:::ui
    click Router "https://github.com/team-phitogether/phitogether/blob/main/src/components/router/index.js"
    click Router "https://github.com/team-phitogether/phitogether/blob/main/src/components/router/routes.js"
    Global["Global & Styles"]:::ui
    click Global "https://github.com/team-phitogether/phitogether/blob/main/src/global.js"
    click Global "https://github.com/team-phitogether/phitogether/blob/main/src/style.css"
    Html["index.html"]:::ui
    click Html "https://github.com/team-phitogether/phitogether/blob/main/index.html"
    Vite["vite.config.js"]:::ui
    click Vite "https://github.com/team-phitogether/phitogether/blob/main/vite.config.js"
  end

  subgraph "Renderer Core"
    direction TB
    RendIndex["renderer/index.ts"]:::ui
    click RendIndex "https://github.com/team-phitogether/phitogether/blob/main/src/components/renderer/index.ts"
    RendClass["renderer/class.ts"]:::ui
    click RendClass "https://github.com/team-phitogether/phitogether/blob/main/src/components/renderer/class.ts"
    RendDir["sim-phi & plugins"]:::ui
    click RendDir "https://github.com/team-phitogether/phitogether/tree/main/src/components/renderer/renderers/sim-phi/"
  end

  subgraph "WASM Module"
    direction TB
    WasmBin["pzEncrypted.wasm"]:::ui
    click WasmBin "https://github.com/team-phitogether/phitogether/blob/main/src/utils/wasm/pzEncrypted.wasm"
    WasmJs["wasm_exec.js"]:::ui
    click WasmJs "https://github.com/team-phitogether/phitogether/blob/main/src/utils/js/wasm_exec.js"
  end

  subgraph "Community APIs"
    direction TB
    API_Phizone["PhiZone API Wrappers"]:::ui
    click API_Phizone "https://github.com/team-phitogether/phitogether/blob/main/src/components/community/phizone/api.ts"
    ERRProc["Error Processor"]:::ui
    click ERRProc "https://github.com/team-phitogether/phitogether/blob/main/src/components/community/phizone/apiErrProcessor.ts"
    Taptap["Taptap API"]:::ui
    click Taptap "https://github.com/team-phitogether/phitogether/blob/main/src/components/community/phizone/taptap.ts"
    User["User Models"]:::ui
    click User "https://github.com/team-phitogether/phitogether/blob/main/src/components/community/phizone/userInfo.type.ts"
    MultiVue["multiplayer.vue"]:::ui
    click MultiVue "https://github.com/team-phitogether/phitogether/blob/main/src/components/multiplayer.vue"
  end

  subgraph "Recording & Replay"
    direction TB
    Record["recordMgr.js"]:::ui
    click Record "https://github.com/team-phitogether/phitogether/blob/main/src/components/recordMgr/recordMgr.js"
    Replay["replayMgr.js"]:::ui
    click Replay "https://github.com/team-phitogether/phitogether/blob/main/src/components/recordMgr/replayMgr.js"
  end

  subgraph "Client-side Storage"
    direction TB
    Ptdb["IndexedDB (ptdb)"]:::storage
    click Ptdb "https://github.com/team-phitogether/phitogether/tree/main/src/components/ptdb/"
  end

  subgraph "Native Shells"
    direction TB
    Android["Android Shell"]:::native
    click Android "https://github.com/team-phitogether/phitogether/blob/main/android/app/src/main/java/fun/phitogether/app/MainActivity.java"
    click Android "https://github.com/team-phitogether/phitogether/blob/main/capacitor.config.json"
    iOS["iOS Shell"]:::native
    click iOS "https://github.com/team-phitogether/phitogether/blob/main/ios/App/App/AppDelegate.swift"
    click iOS "https://github.com/team-phitogether/phitogether/blob/main/ios/App/App/MyViewController.swift"
    click iOS "https://github.com/team-phitogether/phitogether/blob/main/ios/App/App.xcodeproj"
  end

  subgraph "External Services"
    direction TB
    CDN["Static Asset Server (CDN)"]:::external
    click CDN "https://github.com/team-phitogether/phitogether/tree/main/public/"
    PhiZoneAPI["PhiZone Service"]:::external
    TaptapAPI["Taptap Service"]:::external
  end

  Pages -->|"renders with"| RendIndex
  RendIndex -->|"uses plugins"| RendDir
  RendIndex -->|"uses core class"| RendClass
  RendIndex -->|"calls Wasm"| WasmBin
  Pages -->|"loads wasm helper"| WasmJs
  Pages -->|"navigates via"| Router
  Pages -->|"multiplayer logic"| API_Phizone
  Pages -->|"error handling via"| ERRProc
  Pages -->|"taptap integration"| Taptap
  Pages -->|"user info via"| User
  Pages -->|"UI for multiplayer"| MultiVue
  Pages -->|"records gameplay"| Record
  Pages -->|"plays replays"| Replay
  Pages -->|"caches data in"| Ptdb
  Pages -->|"fetches assets"| CDN
  Pages -->|"calls external"| PhiZoneAPI
  Pages -->|"calls external"| TaptapAPI
  Pages -->|"bridges to"| Android
  Pages -->|"bridges to"| iOS

  classDef ui fill:#D0E8FF,stroke:#2B6CB0,color:#2B6CB0
  classDef storage fill:#E6FFFA,stroke:#38A169,color:#38A169
  classDef external fill:#FFF5E6,stroke:#DD6B20,color:#DD6B20
  classDef native fill:#EDF2F7,stroke:#718096,color:#718096
```
