How helicraft-mc/vesper works
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