# verekia/manapotion architecture

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

- Interactive diagram: https://gitdiagram.com/verekia/manapotion
- Repository: https://github.com/verekia/manapotion

## Overview

##### Project type and purpose
- This is an open-source, monorepo toolkit (“Mana Potion”) for JavaScript game development. It provides a set of low-level utilities (input listeners, main loop, virtual joysticks, browser helpers, Tailwind theme) plus framework-specific adapters for React, Vue, Svelte, and vanilla JS.

##### File structure
- Top-level:
- Configuration & CI: Dockerfile, .github/workflows, nginx.conf, deploy.sh, lerna.json
- Packages: `packages/core`, `packages/react`, `packages/vue`, `packages/svelte`, `packages/vanilla`
- Examples: `examples/react`, `examples/vue`, `examples/svelte`, `examples/vanilla`
- Website: docs/demo site under `website`
- Each `packages/*` contains source code for a distributable npm package.
- `packages/core` is the foundational library (listeners, stores, main loop, joystick).
- Other packages import `core` and add framework-specific bindings (hooks/components/stores).
- Examples import the corresponding framework package to demonstrate usage.
- CI/CD files govern testing, linting, building, publishing to npm, and deploying the website.

##### Key README insights
- Core features: Listeners (reactive and non-reactive stores), main loop, virtual joysticks, browser API helpers, Tailwind media queries.
- Adapters (@manapotion/react, vue, svelte, vanilla) wrap core features in idiomatic APIs (hooks, components, stores).
- Examples and demo URLs showcase each integration.
- Versioning via Lerna, breaking changes before 1.0.

a. Main components
- Core Library (`packages/core`)
- Framework Adapters (`packages/react`, `packages/vue`, `packages/svelte`, `packages/vanilla`)
- Example Apps (`examples/*`)
- Documentation/Demo Website (`website`)
- External Services: GitHub (SCM & CI), npm Registry (package hosting), Docker Registry (optional), Discord (community)
b. Relationships & interactions
- Core Library → publishes to npm → consumed by Framework Adapters
- Framework Adapters → publish to npm → consumed by Example Apps & user projects
- Example Apps → import adapters → render game UI & interactive demos
- Website → uses built artifacts & examples → deployed via deploy.sh & nginx
- CI Pipeline → on push publishes packages & deploys website
c. Architectural patterns
- Monorepo managed by Lerna: single repo, multiple packages, shared config
- Layered modular design: core utilities at bottom, adapter wrappers above, consumer applications at top
- CI/CD pipeline orchestrates build, test, publish, deploy
d. Technologies & frameworks
- TypeScript, Vite for bundling examples & website
- Zustand for reactive stores
- Tailwind CSS for styling and media‐query helpers
- Docker & nginx for containerized website deployment
- GitHub Actions for automation

##### Essential elements to capture
- Lerna monorepo root and shared config (.eslint, tsconfig, prettier)
- Core module exporting listeners, loop, joystick, helpers
- Framework adapters importing core and exporting hooks/components
- Example source directories demonstrating adapter usage
- Documentation/demo website pulling from built examples & hosting live demos
- CI pipeline steps and external services (GitHub Actions → npm → Docker Registry → nginx)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Layer
    subgraph "Core Layer"
        Core["Core Library (packages/core)"]:::core
    end

    %% Adapters Layer
    subgraph "Adapters Layer"
        React["React Adapter (packages/react)"]:::adapter
        Vue["Vue Adapter (packages/vue)"]:::adapter
        Svelte["Svelte Adapter (packages/svelte)"]:::adapter
        Vanilla["Vanilla Adapter (packages/vanilla)"]:::adapter
    end

    %% Examples Layer
    subgraph "Examples Layer"
        ExReact["React Example App (examples/react)"]:::example
        ExVue["Vue Example App (examples/vue)"]:::example
        ExSvelte["Svelte Example App (examples/svelte)"]:::example
        ExVanilla["Vanilla Example App (examples/vanilla)"]:::example
    end

    %% Website
    Website["Documentation/Demo Website (website)"]:::website

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        Lerna["Lerna Monorepo (lerna.json)"]:::infra
        CI["CI Pipeline (.github/workflows/check-all.yml)"]:::infra
        Deploy["Deployment Script (deploy.sh)"]:::infra
        Docker["Docker Configuration (Dockerfile)"]:::infra
        Nginx["Nginx Config (nginx.conf)"]:::infra
        Github["GitHub Actions"]:::infra
        Npm["npm Registry"]:::infra
        DockerReg["Docker Registry"]:::infra
    end

    %% Dependencies
    Lerna -->|manages| Core
    Lerna -->|manages| React
    Lerna -->|manages| Vue
    Lerna -->|manages| Svelte
    Lerna -->|manages| Vanilla
    Lerna -->|manages| ExReact
    Lerna -->|manages| ExVue
    Lerna -->|manages| ExSvelte
    Lerna -->|manages| ExVanilla
    Lerna -->|manages| Website

    Core -->|imports| React
    Core -->|imports| Vue
    Core -->|imports| Svelte
    Core -->|imports| Vanilla

    React -->|used by| ExReact
    Vue -->|used by| ExVue
    Svelte -->|used by| ExSvelte
    Vanilla -->|used by| ExVanilla

    ExReact -.->|builds demo| Website
    ExVue -.->|builds demo| Website
    ExSvelte -.->|builds demo| Website
    ExVanilla -.->|builds demo| Website

    Github -->|triggers| CI
    CI -->|builds & tests| Core
    CI -->|builds & tests| React
    CI -->|builds & tests| Vue
    CI -->|builds & tests| Svelte
    CI -->|builds & tests| Vanilla
    CI -->|publishes| Npm
    CI -->|pushes image| DockerReg
    CI -->|deploys| Website

    Website -->|packaged in| Docker
    Docker -->|serves via| Nginx
    Deploy -->|runs| Website

    %% Click Events
    click Core "https://github.com/verekia/manapotion/tree/main/packages/core"
    click React "https://github.com/verekia/manapotion/tree/main/packages/react"
    click Vue "https://github.com/verekia/manapotion/tree/main/packages/vue"
    click Svelte "https://github.com/verekia/manapotion/tree/main/packages/svelte"
    click Vanilla "https://github.com/verekia/manapotion/tree/main/packages/vanilla"
    click ExReact "https://github.com/verekia/manapotion/tree/main/examples/react"
    click ExVue "https://github.com/verekia/manapotion/tree/main/examples/vue"
    click ExSvelte "https://github.com/verekia/manapotion/tree/main/examples/svelte"
    click ExVanilla "https://github.com/verekia/manapotion/tree/main/examples/vanilla"
    click Website "https://github.com/verekia/manapotion/tree/main/website"
    click Lerna "https://github.com/verekia/manapotion/blob/main/lerna.json"
    click CI "https://github.com/verekia/manapotion/blob/main/.github/workflows/check-all.yml"
    click Deploy "https://github.com/verekia/manapotion/blob/main/deploy.sh"
    click Docker "https://github.com/verekia/manapotion/tree/main/Dockerfile"
    click Nginx "https://github.com/verekia/manapotion/blob/main/nginx.conf"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#3B82F6,stroke-width:2px
    classDef adapter fill:#D1FAE5,stroke:#10B981,stroke-width:2px
    classDef example fill:#FEF3C7,stroke:#D97706,stroke-width:2px
    classDef website fill:#FFEDD5,stroke:#F97316,stroke-width:2px
    classDef infra fill:#E5E7EB,stroke:#6B7280,stroke-width:2px
```
