# helicraft-mc/vesper architecture

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

- Interactive diagram: https://gitdiagram.com/helicraft-mc/vesper
- Repository: https://github.com/helicraft-mc/vesper

## Overview

##### Project Type and Purpose
- This is a single-page, server-rendered frontend application built with Nuxt 3 (Vue 3 + TypeScript + Tailwind CSS).
- It serves as the UI for the HeliCraft Minecraft server, fetching dynamic data from a separate Teapot backend and rendering static/content pages via @nuxt/content.

##### File-Structure Analysis
- Top-level configuration and deployment:
- Dockerfile, .dockerignore, ecosystem.config.cjs (PM2), .env.example
- nuxt.config.ts, tsconfig.json, package.json
- Frontend source:
- app.vue, assets/ (styles, fonts), components/ (grouped by feature: account, alliances, states, history, ui)
- composables/ (useApiFetch, usePlanFetch)
- layouts/, pages/ (folder structure mirrors routes, including dynamic and nested panels under /states/[uuid]/panel)
- plugins/api-fetch.ts (configures fetch proxy and auth)
- content/ (markdown pages via @nuxt/content)
- Server/API:
- server/api/intro-images.get.ts (Nuxt Nitro server route to serve public intro images)
- Types and shared enums: types/*.ts

##### README Insights
- Key technologies: Nuxt 3, TypeScript, Tailwind CSS
- Nuxt modules: @pinia/nuxt, @nuxtjs/tailwindcss, @nuxt/image, @nuxt/content, @nuxtjs/turnstile, @sidebase/nuxt-auth
- Dev features: API proxy routes (/distant-api/**, /plan-api/**), automatic token refresh, commit badge, custom nuxt.config.ts

##### Components
a. Frontend Client (Browser)
b. Nuxt SSR/Server (Node/Nitro)
- Static asset handler (public/, assets/)
- Content module (content/pages via @nuxt/content)
- Server routes (server/api/intro-images.get)
- Proxy middleware (/distant-api → Teapot backend, /plan-api → plan service)
- Auth layer (Nuxt-Auth + Cloudflare Turnstile)
- State management (Pinia stores via composables)
c. External Backend Service (“Teapot” API)
d. Third-party Services
- Cloudflare Turnstile (bot protection)
- CDN/Font hosting (@nuxt/fonts, @nuxt/image)

##### Relationships and Data Flows
- Browser ↔ Nuxt SSR (initial page render, hydration, route navigation)
- Nuxt SSR → server/api (internal Nitro routes)
- Nuxt SSR → external Teapot API (via proxy middleware)
- Nuxt SSR ↔ Pinia (global state)
- Nuxt SSR → @nuxt/content (load markdown pages)
- Browser → Cloudflare Turnstile (challenge widget)
- Browser ← static assets from CDN/public

##### Architectural Patterns and Principles
- Modular, feature-grouped UI components (atomic design per feature: account, alliances, states, etc.)
- Composables for reusable data-fetch logic (DRY)
- Proxy pattern for backend decoupling (local /distant-api/**)
- SSR/SSG hybrid: static content served, dynamic pages server-rendered
- State management (Pinia) to centralize client state and tokens

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Browser (User)"]:::frontend
    Cloudflare["Cloudflare Turnstile"]:::third
    CDN["CDN / Font Hosting"]:::third

    %% Application Server Layer
    subgraph "Nuxt Application"
        direction TB
        Config["nuxt.config.ts"]:::server
        StaticAssets["assets/"]:::server
        PublicAssets["public/"]:::server
        ContentConfig["content.config.ts"]:::server
        ContentPages["content/pages"]:::server
        AppVue["app.vue"]:::server
        Layouts["layouts/"]:::server
        Pages["pages/"]:::server
        NitroRoute["server/api/intro-images.get.ts"]:::server
        Plugin["plugins/api-fetch.ts"]:::server
        Auth["Auth Module"]:::server
        Store["Pinia Store & Composables"]:::server
        ComposableAPI["useApiFetch.ts"]:::server
        ComposablePlan["usePlanFetch.ts"]:::server
    end

    %% External Backends
    Teapot["Teapot API"]:::external

    %% Relationships
    Browser -->|Initial Page Request| AppVue
    Browser -->|Challenges| Cloudflare
    Browser -->|Fetch Static Assets| CDN

    AppVue -->|Renders Layouts & Pages| Layouts
    AppVue -->|Renders Pages| Pages
    AppVue -->|Reads Config| Config
    AppVue -->|Loads Assets| StaticAssets
    AppVue -->|Serves Public Files| PublicAssets
    AppVue -->|Loads Markdown| ContentPages
    AppVue -->|Reads Content Config| ContentConfig
    AppVue -->|Invokes Nitro Routes| NitroRoute
    AppVue -->|Uses Proxy| Plugin
    Plugin -->|Proxy→Teapot| Teapot
    AppVue -->|Auth Flows| Auth
    Cloudflare -->|Verification| Auth
    AppVue -.->|Reads/Writes| Store
    Auth -.->|Token Storage| Store
    Store -->|API Helpers| ComposableAPI
    Store -->|Plan Helpers| ComposablePlan

    %% Click Events
    click Config "https://github.com/helicraft-mc/vesper/blob/master/nuxt.config.ts"
    click StaticAssets "https://github.com/helicraft-mc/vesper/tree/master/assets/"
    click PublicAssets "https://github.com/helicraft-mc/vesper/tree/master/public/"
    click ContentConfig "https://github.com/helicraft-mc/vesper/blob/master/content.config.ts"
    click ContentPages "https://github.com/helicraft-mc/vesper/tree/master/content/pages"
    click AppVue "https://github.com/helicraft-mc/vesper/blob/master/app.vue"
    click Layouts "https://github.com/helicraft-mc/vesper/tree/master/layouts/"
    click Pages "https://github.com/helicraft-mc/vesper/tree/master/pages/"
    click NitroRoute "https://github.com/helicraft-mc/vesper/blob/master/server/api/intro-images.get.ts"
    click Plugin "https://github.com/helicraft-mc/vesper/blob/master/plugins/api-fetch.ts"
    click ComposableAPI "https://github.com/helicraft-mc/vesper/blob/master/composables/useApiFetch.ts"
    click ComposablePlan "https://github.com/helicraft-mc/vesper/blob/master/composables/usePlanFetch.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef server fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef third fill:#E1BEE7,stroke:#8E24AA,color:#000
```
