bebe/bamort
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7c36a1332715f8371c345351e886c5335d08be05
bamort/Bamort_detailed_project_documentation.md
T

1088 lines
55 KiB
Markdown
Raw Normal View History

ai documentation
2026-04-01 15:16:12 +02:00
# Bamort — Detailed Project Documentation
> Version: 0.2.4 (backend) / 0.2.3 (frontend)
> Generated: 2026-03-13
> Purpose: Comprehensive architecture, component, and business-logic reference
---
## Table of Contents
1. [Project Purpose and Domain](#1-project-purpose-and-domain)
2. [High-Level Architecture](#2-high-level-architecture)
3. [Technology Stack](#3-technology-stack)
4. [Backend Architecture](#4-backend-architecture)
- [Entry Point and Startup Sequence](#41-entry-point-and-startup-sequence)
- [Router and Middleware](#42-router-and-middleware)
- [Authentication System](#43-authentication-system)
- [Module Breakdown (Functional View)](#44-module-breakdown-functional-view)
5. [Frontend Architecture](#5-frontend-architecture)
- [Application Bootstrap](#51-application-bootstrap)
- [Router and Navigation Guards](#52-router-and-navigation-guards)
- [State Management (Pinia Stores)](#53-state-management-pinia-stores)
- [Views and Components (Functional View)](#54-views-and-components-functional-view)
- [API Communication Layer](#55-api-communication-layer)
6. [Core Business Logic](#6-core-business-logic)
- [Character Data Model](#61-character-data-model)
- [Derived Values Calculation](#62-derived-values-calculation)
- [Skill and Spell Learning System](#63-skill-and-spell-learning-system)
- [Character Creation Wizard](#64-character-creation-wizard)
- [PDF Export Pipeline](#65-pdf-export-pipeline)
- [Audit Log](#66-audit-log)
7. [Data Access and Persistence](#7-data-access-and-persistence)
8. [Module Interaction Map](#8-module-interaction-map)
9. [Complete API Route Reference](#9-complete-api-route-reference)
10. [Infrastructure and Deployment](#10-infrastructure-and-deployment)
11. [User Roles and Access Control](#11-user-roles-and-access-control)
12. [Internationalisation (i18n)](#12-internationalisation-i18n)
13. [Known Limitations and Security Notes](#13-known-limitations-and-security-notes)
---
## 1. Project Purpose and Domain
**Bamort** (BaMoRT = *Ba*sic Mo*R*phing *T*ool) is a web-based character management system for the **Midgard** tabletop role-playing game (M5 system). It is designed as a replacement for the older MOAM desktop application.
**Core user-facing features:**
- Create, manage, and view RPG characters (stats, skills, spells, equipment)
- Guide new users through a multi-step character creation wizard following Midgard M5 rules
- Manage skill and spell learning progression with rule-enforced costs (EP, TE, LE, gold)
- Track experience points (EP), practice points (PP), and wealth (gold/silver/copper)
- Export characters as PDF character sheets via HTML templates
- Import/export characters as JSON or CSV for interoperability with other tools
- Share characters between users (read-only or read/write)
- Maintain game-system master data (canonical skill, spell, and equipment tables)
**Business domain vocabulary:**
| Term | Meaning |
|------|---------|
| Char / Character | A player or NPC character in the game |
| Grad | Character level/grade |
| EP | Experience points — spent to improve skills and spells |
| TE | Training entries — attempts needed to improve a skill |
| LE | Learning entries — prerequisite step counts for spells |
| PP | Practice points — earned in combat/use, reduce learning costs |
| Fertigkeit | Skill (e.g., Schwimmen, Klettern) |
| Waffenfertigkeit | Weapon skill (subtype of Fertigkeit) |
| Zauber | Spell (magical ability) |
| Eigenschaft | Attribute (St=Strength, Gs=Dexterity, Gw=Agility, Ko=Constitution, In=Intelligence, Zt=Magical Talent, Au=Appearance, Wk=Willpower, Pa=Parry) |
| Rasse | Race (Mensch, Zwerg, Elf, etc.) |
| Typ | Character class code (Kr=Knight, Ma=Mage, Hx=Witch, etc.) |
| Lp / Ap / B | Life Points / Action Points / Load capacity |
| Bennies (Gg/Gp/Sg) | Luck tokens used in gameplay |
| Vermoegen | Wealth in gold/silver/copper pieces |
| Abwehr | Derived defense value |
| GSMaster | Game-system master data (canonical tables for skills, spells, equipment) |
| M5 | Midgard 5th edition rule set (the game system code used) |
---
## 2. High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ User (Browser) │
└──────────────────────────┬──────────────────────────────────────┘
│ HTTP / HTTPS
┌──────────────────────────▼──────────────────────────────────────┐
│ Vue 3 SPA (bamort-frontend) │
│ Vite dev server (port 5173) / Nginx (port 80) │
│ - Vue Router (client-side navigation) │
│ - Pinia (state management) │
│ - vue-i18n (DE/EN translations) │
│ - Axios (API calls to backend) │
└──────────────────────────┬──────────────────────────────────────┘
│ REST API calls to VITE_API_URL
│ Bearer token in Authorization header
┌──────────────────────────▼──────────────────────────────────────┐
│ Go / Gin REST API (bamort-backend) │
│ Port 8180 │
│ - Public routes: /register /login /password-reset/* │
│ - Protected routes: /api/* (auth middleware enforced) │
│ - Public info routes: /api/public/* │
└──────────────────────────┬──────────────────────────────────────┘
│ GORM
┌──────────────────────────▼──────────────────────────────────────┐
│ MariaDB 11.4 │
│ (bamort-mariadb, port 3306) │
│ Production: not exposed to host network │
│ Dev: accessible at localhost:3306 + phpMyAdmin at :8081 │
└─────────────────────────────────────────────────────────────────┘
```
The frontend communicates **directly** with the backend API via the `VITE_API_URL` environment variable — there is no Nginx reverse-proxy layer between them in production (TLS termination is the responsibility of an external proxy like Traefik).
---
## 3. Technology Stack
| Layer | Technology | Version | Purpose |
|-------|-----------|---------|---------|
| Backend language | Go | 1.25 | API server, business logic |
| Backend framework | Gin | latest | HTTP routing, middleware |
| ORM | GORM | latest | Database access, migrations |
| Database | MariaDB | 11.4 | Primary persistent storage |
| Test DB | SQLite | (via CGO) | Isolated per-test snapshot |
| PDF rendering | chromedp + Chromium | latest | HTML→PDF via headless browser |
| PDF merging | pdfcpu | latest | Multi-page PDF assembly |
| Live reload (dev) | Air | latest | Backend hot-reload during development |
| Frontend framework | Vue 3 | ^3.5.13 | UI (Options API) |
| Frontend build | Vite | ^6.0.1 | Dev server + production bundler |
| State management | Pinia | ^2.3.0 | Reactive global stores |
| HTTP client | Axios | ^1.7.9 | API communication with auth interceptors |
| i18n | vue-i18n | ^11.0.0 | German/English UI localisation |
| Frontend server | Nginx (prod) / Vite (dev) | alpine / 6.x | Static file serving + SPA routing |
| Container runtime | Docker + Docker Compose | — | Isolated service deployment |
---
## 4. Backend Architecture
### 4.1 Entry Point and Startup Sequence
**File:** `backend/cmd/main.go`
The `main()` function orchestrates startup in this order:
1. **Load configuration** — reads `.env` / `.env.local` then environment variable overrides via `config.Cfg` (auto-loaded in `config.init()`)
2. **Configure logger** — sets log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) and debug mode based on config
3. **Set Gin mode** — `gin.ReleaseMode` in production, `gin.DebugMode` otherwise
4. **Connect database** — calls `database.ConnectDatabase()` which selects MySQL or SQLite based on `DATABASE_TYPE` and `ENVIRONMENT`
5. **Initialize PDF templates** — copies default templates from `/app/default_templates` to `cfg.TemplatesDir` if needed via `pdfrender.InitializeTemplates()`
6. **Set up Gin engine** — calls `router.SetupGin(r)` for CORS config
7. **Register routes** — each module calls `RegisterRoutes(protected)` on the protected `/api` group
8. **Register public routes** — pdfrender and appsystem register unauthenticated endpoints
9. **Start HTTP server** — `r.Run(cfg.GetServerAddress())`
### 4.2 Router and Middleware
**File:** `backend/router/routes.go` and `backend/router/setup.go`
**Route structure:**
```
POST /register → user.RegisterUser
POST /login → user.LoginUser
POST /password-reset/request → user.RequestPasswordReset
GET /password-reset/validate/:token → user.ValidateResetToken
POST /password-reset/reset → user.ResetPassword
/api/* ← ALL require valid Bearer token via user.AuthMiddleware()
├── /api/public/version → appsystem (no auth check inside group, separate route)
├── /api/public/systeminfo → appsystem
├── /api/user/* → user module
├── /api/users/* → user module (admin-only subset)
├── /api/characters/* → character module
├── /api/maintenance/* → gsmaster (read) + maintenance (maintainer-only write)
├── /api/importer/* → importer module
├── /api/pdf/* → pdfrender module
├── /api/transfer/* → transfer module
└── /api/appsystem/* → appsystem module
```
**CORS:** Configured in `router/setup.go` with allowed origins including `localhost:5173` (dev), `localhost:8180`, and configurable `BASE_URL` (production frontend).
### 4.3 Authentication System
**Token generation** (`user/handlers.go` → `GenerateToken`):
- Hashes `username + createdAt` with MD5
- Embeds the user's ID in an predictable position within the hex string
- Token is stored client-side in `localStorage`
**Token validation** (`user/handlers.go` → `CheckToken`):
- Extracts the Base64/hex-encoded user ID from position `len("Bearer ")` onward in the `Authorization` header
- Loads the user from the database by that ID
- **No cryptographic signature verification is performed** — this is a design limitation (see Section 13)
**AuthMiddleware:**
- Calls `CheckToken`, sets `userID`, `username`, `user` in the Gin context
- Returns `401 Unauthorized` if token is absent or user not found
**Password hashing:** MD5 (`crypto/md5`). The bcrypt implementation is present but commented out.
### 4.4 Module Breakdown (Functional View)
Each module follows the same structure: `handlers.go` (business logic + HTTP responses), `routes.go` (route registration), and `*_test.go` (tests).
---
#### `user/` — User Account Management
**Business function:** Registration, login, profile management, password reset via email, and role-based access control.
**Key responsibilities:**
- `RegisterUser` — creates a new user with MD5-hashed password and default `standard` role
- `LoginUser` — validates credentials, returns a token
- `AuthMiddleware` — protects all `/api/*` routes; injects user context
- `RequireAdmin()` / `RequireMaintainer()` — role-check middleware used on specific sub-routes
- Profile endpoints: `GET/PUT /api/user/profile`, display name, email, preferred language, password change
- Admin user management: `GET/PUT/DELETE /api/users/:id`
- Password reset flow: request → email with token → validate token → set new password (uses `mail/` module for SMTP)
**Roles:**
| Role | Permissions |
|------|------------|
| `standard` | Own characters + shared characters |
| `maintainer` | + Write access to GSMaster data and maintenance endpoints |
| `admin` | + User management (list, change role, delete, reset password) |
---
#### `character/` — Character Management (Core Module)
**Business function:** The heart of the application. Full CRUD for characters plus all RPG game-logic operations.
**Sub-responsibilities:**
| Sub-area | Files | Business purpose |
|----------|-------|-----------------|
| CRUD | `handlers.go`, `database.go` | Create / read / update / delete characters and their sub-entities (attributes, skills, spells, equipment) |
| Derived values | `derived_values_calculator.go` | Calculate secondary stats (Abwehr, Zaubern, Raufen, body/mind resistance) from primary attributes using M5 formulas |
| Derived values (dice) | `derived_values_calculator.go` | Calculate dice-dependent stats during character creation (Lp_max, Ap_max, B_max, PA, Wk) requiring die-roll input from frontend |
| Learning cost engine | `lerncost_handler.go` | Compute EP/TE/LE/gold cost to learn a new skill/spell or improve an existing one, considering class, category, difficulty, practice points, and reward bonuses |
| Skill actions | `handlers.go` | Add/remove/edit skills and weapon skills inline |
| Learn skill | Separate handler | Learn a new skill (deducts resources, creates audit log entries) |
| Improve skill | `ImproveSkill` handler | Increase an existing skill value (validates costs, writes audit trail) |
| Learn spell | `LearnSpell` handler | Add a new spell to the character |
| Practice points | `practice_points_handler.go` | Track PP per skill category; PP reduce TE costs in learning |
| Experience & wealth | `handlers.go` | Update EP/gold separately from full character update |
| Character sharing | `share_handlers.go` | Grant read or write access to specific other users |
| Character creation wizard | Multiple handlers | Multi-step session-based creation: basic info → attributes → derived rolling → skills → finalize |
| Creation rules | `creation_rules.go` | M5-specific tables for special abilities (W100 roll → bonus/malus), starting attribute bonuses by race/class |
| Audit log | `audit_log.go`, `audit_log_handlers.go` | Immutable log of EP/gold/stat changes with reason codes |
| Image | `image_handler.go` | Upload and store Base64 character portrait |
| Ownership guard | `ownership_guard_test.go` | Ensures only the owner (or share-granted user) can modify |
| System info | `system_information_handlers.go` | Returns available skill categories for UI dropdowns |
---
#### `gsmaster/` — Game-System Master Data
**Business function:** Canonical reference tables for the M5 game system. Skills, weapon skills, spells, equipment, weapons, and containers as defined by the Midgard rules. Users with the `maintainer` role can edit these tables.
**Read (all authenticated users):**
- `GET /api/maintenance/skills` — list all skills
- `GET /api/maintenance/spells` — list all spells
- `GET /api/maintenance/weapons` — list all weapons
- `GET /api/maintenance/equipment` — general equipment
- `GET /api/maintenance/*-enhanced` — enhanced views with additional metadata (learning costs, categories, etc.)
**Write (maintainer only):**
- POST/PUT/DELETE on all the above categories
**Learning cost integration:** `gsmaster` package provides lookup helpers used by the `character` module to calculate learning costs. Skills carry `Category`, `Difficulty`, and `InnateSkill` properties that drive cost lookup logic.
---
#### `equipment/` — Character Equipment Management
**Business function:** CRUD operations specifically for the equipment attached to a character — weapons (`EqWaffe`), containers/bags (`EqContainer`), transportation (`EqContainer` with `IsTransportation=true`), and general gear (`EqAusruestung`).
**Why separate from `character/`?** Equipment has its own handlers/routes to keep the character module focused on core stats and skills. Equipment can also reference master data items from `gsmaster/`.
---
#### `pdfrender/` — PDF Character Sheet Export
**Business function:** Generate printable PDF character sheets by rendering HTML templates with character data using a Chromium headless browser, then merging the resulting per-page PDFs into a single file.
**Flow:**
1. `ExportCharacterToPDF` receives a character ID and template name
2. Loads the character from the database (fully preloaded)
3. For each template page (page1_stats.html, page2_play.html, etc.):
- Injects character data into the HTML template using Go template engine
- Renders it to PDF via `chromedp` (headless Chromium)
- Checks `<!-- MaxItems: N -->` comment in template to detect overflow
- Generates continuation pages (page1.2_stats.html) for overflow
4. Merges all page PDFs with `pdfcpu` into one file
5. Saves to `cfg.ExportTempDir` and returns the filename
6. Frontend opens a download URL in a new window
**Templates:** Located in `backend/templates/Default_A4_Quer/`. The `InitializeTemplates` function copies the default template to the runtime directory on first run.
**Routes:**
- `GET /api/pdf/export/:id` — export, returns `{"filename": "..."}`
- `GET /api/pdf/file/:filename` — download the generated PDF (public route, no auth required, filename-based security)
- `GET /api/pdf/templates` — list available templates
- `POST /api/pdf/cleanup` — clean up old generated PDF files
---
#### `importer/` — VTT / CSV Import and Export
**Business function:** Import characters from Virtual Tabletop (VTT) JSON format or CSV files. Export characters to VTT JSON or CSV. Export/import spell lists via CSV.
**Routes:**
```
POST /api/importer/upload — Upload VTT JSON + optional CSV
POST /api/importer/spells/csv — Import spell data from CSV
GET /api/importer/export/vtt/:id — Export character as VTT JSON (API response)
GET /api/importer/export/vtt/:id/file — Export character as VTT JSON (file download)
GET /api/importer/export/csv/:id — Export character as CSV
GET /api/importer/export/spells/csv — Export all spells as CSV
```
---
#### `transfer/` — JSON Backup and Restore
**Business function:** Portable character backup/restore in a Bamort-native JSON format. Also supports full-database export/import (admin/migration use case).
**Routes:**
```
GET /api/transfer/export/:id — Export character as JSON
GET /api/transfer/download/:id — Download character JSON as file
POST /api/transfer/import — Import character from JSON
POST /api/transfer/database/export — Export entire database as JSON
POST /api/transfer/database/import — Import full database from JSON
```
---
#### `maintenance/` — Admin and Database Operations
**Business function:** Maintainer-only admin operations: database consistency checks, re-connect/reload env, data migration (SQLite→MariaDB), and managing auxiliary master data not covered by `gsmaster/`.
**Key operations:**
- `GET /api/maintenance/setupcheck` — validate database schema integrity
- `GET /api/maintenance/setupcheck-dev` — extended dev-mode diagnostics
- `GET /api/maintenance/reconndb` — reconnect database (useful after connection interruption)
- `GET /api/maintenance/reloadenv` — reload environment variables at runtime
- `POST /api/maintenance/transfer-sqlite-to-mariadb` — one-time data migration
- CRUD for beliefs (`gsm-believes`), game systems, literature sources, misc lookups, skill improvement cost tables
---
#### `appsystem/` — System Information
**Business function:** Exposes version and system health information.
**Routes:**
```
GET /api/public/version — { version, gitCommit }
GET /api/public/systeminfo — { version, gitCommit, userCount, charCount, dbVersion }
```
These are reachable without authentication (used by `LandingView` and `SystemInfoView` to display status without requiring login).
---
#### `gamesystem/` — Game System Records
**Business function:** Manages `GameSystem` records in the database (e.g., M5 = Midgard 5th edition). Used when creating characters and as a FK reference in master data. Initial seed data creates the M5 game system if it doesn't exist.
---
#### `logger/` — Application Logging
**Business function:** Custom structured logger with levels (DEBUG/INFO/WARN/ERROR). Used throughout all packages. Debug mode controlled by config.
---
#### `mail/` — Email Delivery
**Business function:** SMTP client used exclusively for password-reset emails. Supports TLS (port 465) and STARTTLS (port 587). Configured via `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM` env vars.
---
## 5. Frontend Architecture
### 5.1 Application Bootstrap
**`src/main.js`** registers plugins in order:
1. **Pinia** — state store (must be first)
2. **Vue Router** — client-side routing
3. **vue-i18n** — i18n instance created and exported from `stores/languageStore.js`
4. **UtilsPlugin** — installs global utilities on all components: `$formatDate`, `$formatDateTime`, `$formatRelativeDate`, `$safeValue`, `$capitalize`, `$rollDie`, `$rollDice`, `$rollDiceWithSum`, `$rollNotation`, `$randomBetween`, `$randomChoice`, `$shuffleArray`
**`App.vue`** — root component:
- Shows `<Menu />` only when `localStorage.getItem('token')` is truthy
- Applies `.full-width` CSS class on `<main>` for non-logged-in pages (centers login/register forms)
- Reacts to `storage` and `auth-changed` window events to update `loggedIn` state reactively
### 5.2 Router and Navigation Guards
**File:** `src/router/index.js`
Uses `createWebHistory` (HTML5 pushstate — no hash URLs). Unauthenticated landing/auth pages are statically imported; all other views are lazy-loaded (code-split) for performance.
**Navigation guard logic (beforeEach):**
1. If route requires auth and user is not logged in → redirect to `/login`
2. If route requires admin role → lazy-load `userStore`, fetch profile if not loaded, check `isAdmin` getter → redirect to `/dashboard` if not admin
3. Otherwise → allow navigation
`isLoggedIn()` from `utils/auth.js` simply checks for a token in `localStorage`.
### 5.3 State Management (Pinia Stores)
**`userStore` (`src/stores/userStore.js`)**
Central user identity state. Used by `Menu.vue`, `CharacterDetails.vue`, `UserManagementView.vue`, and the router guard.
| State | Purpose |
|-------|---------|
| `currentUser` | Logged-in user object `{ id, username, display_name, email, role, preferred_language }` |
| `isLoading` | Loading flag for profile fetch |
| Getter | Returns |
|--------|---------|
| `isAuthenticated` | `true` if `currentUser` is not null |
| `userRole` | `currentUser.role` or `'standard'` |
| `isAdmin` | `role === 'admin'` |
| `isMaintainer` | `role === 'maintainer'` or `'admin'` |
| `isStandardUser` | any logged-in user |
Action `fetchCurrentUser()` calls `GET /api/user/profile`, hydrates `currentUser`, and also sets the UI language to the user's preferred language.
---
**`languageStore` (`src/stores/languageStore.js`)**
Holds current language (`de` or `en`). Unusually, the `i18n` instance itself is **created and exported from this file**, then imported in `main.js`. This coupling means language changes can be made from anywhere that imports `i18n`.
---
**`characterCreationStore` (`src/stores/characterCreation.js`)**
In-memory wizard state for multi-step character creation. Tracks current step (1–5), and partial data for each step. The actual server-side session persistence is handled directly by `CharacterCreation.vue` via API calls; the Pinia store mirrors this state in memory.
### 5.4 Views and Components (Functional View)
#### Public Pages (no auth required)
| Component | Route | Purpose |
|-----------|-------|---------|
| `LandingView` | `/` | Landing page; polls `GET /api/public/version` every 5s (up to 24 retries) to show backend status; disables login button until backend responds |
| `LoginView` → `LoginForm` | `/login` | Login form; on success stores token in `localStorage`, triggers `auth-changed` event |
| `RegisterView` → `RegisterForm` | `/register` | Registration form |
| `ForgotPasswordView` → `ForgotPasswordForm` | `/forgot-password` | Sends password-reset email request |
| `ResetPasswordView` → `ResetPasswordForm` | `/reset-password` | Accepts reset token from URL, sets new password |
| `HelpView` | `/help` | FAQ page built from i18n keys dynamically |
| `SponsorsView` | `/sponsors` | Static credits/sponsor page |
| `SystemInfoView` | `/system-info` | Shows system versions and live backend stats |
#### Authenticated Pages
| Component | Route | Purpose |
|-----------|-------|---------|
| `DashboardView` → `CharacterList` | `/dashboard` | Lists own and shared characters; shows active creation sessions; "Create New Character" button starts a new wizard session |
| `UserProfileView` | `/profile` | Self-service: change display name, language, email, password |
| `UserManagementView` | `/users` | Admin-only: list all users, change roles, delete users, reset passwords |
| `MaintenanceView` → `Maintenance` | `/maintenance` | Maintainer tools: database checks, master data management |
| `FileUploadPage` | `/upload` | Import VTT JSON + optional CSV |
| `AusruestungView` → `AusruestungList` | `/ausruestung/:characterId` | Standalone equipment list (legacy view) |
| `CharacterDetails` | `/character/:id` | Main character hub (see below) |
| `CharacterCreation` | `/character/create/:sessionId` | Multi-step character creation wizard |
#### CharacterDetails Component — Central Hub
`CharacterDetails.vue` is the most complex component. It:
1. Fetches full character data from `GET /api/characters/:id`
2. Determines `isOwner` by comparing `character.user_id` vs `userStore.currentUser.id`
3. Renders a **dynamic sub-component** (`<component :is="currentView">`) driven by a submenu
4. Passes `character` and `isOwner` as props to every sub-view
5. Listens for `@character-updated` events from sub-views to trigger a full data reload
**Sub-views (tabs):**
| Component | Business purpose |
|-----------|----------------|
| `DatasheetView` | Character biography, attributes (Au/Gs/Gw/In/Ko/St/Wk/Zt/PA), derived stats (Lp/Ap/B, Abwehr, Zaubern, Raufen, Resistenz), bennies, wealth. Inline double-click editing for owners |
| `SkillView` | Skills grouped by category. Learning mode (toggle 🎓) reveals resources (EP, Gold) and action buttons: learn new skill, improve existing, add manually |
| `WeaponView` | Weapon skills and equipped weapons |
| `SpellView` | Spell list with learn/improve actions |
| `EquipmentView` | Containers, general equipment, transported items |
| `ExperianceView` | Experience and wealth tracking; audit log access |
| `DeleteCharView` | Confirmation UI for deleting the character (owner only) |
| `AuditLogView` | Read-only history of EP/gold changes |
**Overlay dialogs accessible from CharacterDetails:**
- `ExportDialog` — multi-format export: choose PDF template, VTT JSON, or BaMoRT JSON and trigger download
- `VisibilityDialog` — toggle character between public/private (owner only)
#### Learning Dialogs
`SkillLearnDialog.vue`, `SkillImproveDialog.vue`, `SpellLearnDialog.vue` are modal dialogs that:
1. Call `POST /api/characters/lerncost-new` with skill name, current level, type, and action
2. Display the computed cost breakdown (EP, TE, LE, gold, PP reduction)
3. Allow the user to confirm → backend executes the learning/improvement and deducts resources
### 5.5 API Communication Layer
**File:** `src/utils/api.js`
A pre-configured Axios instance:
- `baseURL`: `import.meta.env.VITE_API_URL || 'https://bamort-api.trokan.de'`
- **Request interceptor:** Injects `Authorization: Bearer <token>` from `localStorage` automatically
- **Response interceptor:** On `401`, removes the stale token from `localStorage` and logs a warning (but does not redirect — the nav guard handles that on next navigation)
All components and stores import this `API` instance. Raw `axios` (without the interceptor) is used only in `LandingView` and `SystemInfoView` for unauthenticated public API calls.
---
## 6. Core Business Logic
### 6.1 Character Data Model
The character data model maps closely to the **Midgard M5 character sheet**:
```
Char (root entity, table: char_chars)
├── Eigenschaften[] — 9 primary attributes (Au, Gs, Gw, In, Ko, St, Wk, Zt, PA)
├── Lp — Life points (current + max)
├── Ap — Action points (current + max)
├── B — Load/burden capacity (current + max)
├── Merkmale — Physical description (eye/hair color, height, etc.)
├── Erfahrungsschatz — EP (experience points) + ES (experience treasure/milestone)
├── Bennies — Luck tokens: Gg (lucky coin), Gp (lucky penny), Sg (lucky stroke)
├── Vermoegen — Wealth: Goldstuecke, Silberstuecke, Kupferstuecke
├── Fertigkeiten[] — Skills (Fertigkeit), each with value, base, bonus, PP, category
├── Waffenfertigkeiten[] — Weapon skills (subtype with additional combat fields)
├── Zauber[] — Spells with description, bonus, source reference
├── Waffen[] — Equipped weapons (EqWaffe) with attack/defense bonuses
├── Behaeltnisse[] — Bags/containers (EqContainer)
├── Transportmittel[] — Vehicles (EqContainer with IsTransportation=true)
├── Ausruestung[] — General equipment items
└── Spezialisierung — JSON array of specialization strings
```
**`FeChar`** (Frontend Character) is the API response type: it embeds `Char` plus computed fields:
- `Git` (poison tolerance = 30 + Ko/2)
- `CategorizedSkills` — map grouping skills by category for `SkillView` rendering
- `InnateSkills` — innate/racial skills separated from learned ones
### 6.2 Derived Values Calculation
**File:** `backend/character/derived_values_calculator.go`
The backend implements the M5 formula set. Key derivations:
| Derived value | Formula |
|--------------|---------|
| AusdauerBonus | Ko/10 + St/20 |
| SchadensBonus | St/20 + Gs/30 − 3 |
| AngriffsBonus | Gs/20 + Gw/30 − 3 |
| AbwehrBonus | Gw/20 + Gs/30 − 3 |
| ZauberBonus | In/10 + Zt/20 − 3 |
| ResistenzBonusKoerper | Ko/10 + Wk/20 − 3 |
| ResistenzBonusGeist | In/10 + Wk/15 − 3 |
| Abwehr | (grade-based base) + AbwehrBonus + PA (parry) |
| Zaubern | (class-based base) + ZauberBonus |
| Raufen | (class-based base at Grad 1) |
Dice-dependent values (rolled during character creation) include: `lp_max`, `ap_max`, `b_max`, `pa` (parry), `wk` (willpower). The frontend rolls dice and sends the results to `POST /api/characters/create-session/:id/derived` where the server validates and stores them.
The frontend component in `CharacterCreation.vue` exposes the dice-roll UI and calls `GET /api/characters/calculate-static-fields` and `POST /api/characters/calculate-rolled-field` to get the values computed by the backend rather than computing them in JavaScript.
### 6.3 Skill and Spell Learning System
**File:** `backend/character/lerncost_handler.go`
The learning cost engine computes what it costs (EP + TE, or EP + LE for spells) to learn a new skill/spell or improve an existing one. This is the most complex piece of business logic in the application.
**Input:**
```json
{
"name": "Klettern",
"type": "skill",
"action": "improve",
"current_level": 10,
"target_level": 12,
"use_pp": 2,
"reward": { "type": "half_ep_improvement" }
}
```
**Processing steps:**
1. Look up the character's class abbreviation (`Typ`)
2. Normalize the skill/spell name (trim, lowercase for lookup)
3. Find the skill in `gsmaster` master data to get `Category` and `Difficulty`
4. Query learning cost tables:
- For **skills**: `ClassCategoryEPCost` (EP per TE by class+category) + `SkillImprovementCost` (TE per level step) + `SkillCategoryDifficulty` (base LE)
- For **spells**: `ClassSpellSchoolEPCost` (EP per LE by class+spell school) + `SpellLevelLECost` (LE by spell level)
- For **weapon skills**: separate weapon skill cost tables
5. Apply **practice points (PP)** reduction: each PP reduces required TE by 1 (capped at max PP available for category)
6. Apply **reward bonuses** if specified:
- `free_learning` — zero cost
- `free_spell_learning` — zero cost for spells
- `half_ep_improvement` — halve EP cost when improving
- `gold_for_ep` — substitute up to half the EP with 10 GS each
7. Return full cost breakdown plus `CanAfford` flag comparing costs to character's current EP/gold
For **improve** action, costs are computed **per level step** from `current_level+1` to `target_level` and aggregated: `MultiLevelCostResponse` contains both per-step and total costs.
The `ImproveSkill` and `LearnSkill` handlers execute the actual resource deduction and write audit log entries.
### 6.4 Character Creation Wizard
**Backend:** `backend/character/` (multiple handlers)
**Frontend:** `frontend/src/components/CharacterCreation.vue` and `CharacterCreation/` sub-components
**Session storage:** `models.CharacterCreationSession` (table: `char_creation_sessions`)
The wizard is a **server-side session** model. A session stores partial character data as JSON blobs per step. Sessions expire (stored `ExpiresAt`).
**Steps:**
| Step | Name | Backend endpoint | Data stored |
|------|------|-----------------|-------------|
| 1 | Basic Info | `PUT .../basic` | Name, race, class, origin, social class, faith, gender, handedness |
| 2 | Attributes | `PUT .../attributes` | Primary attributes (rolled client-side, validated server-side) |
| 3 | Derived Values | `PUT .../derived` | Dice-rolled derived stats (LP/AP/B/PA/Wk) |
| 4 | Skills | `PUT .../skills` | Selected starting skills with initial values |
| 5 | Finalize | `POST .../finalize` | Creates the final `Char` record from all session data |
**Available-skills-for-creation endpoint** (`POST /api/characters/available-skills-creation`):
Returns all learnable skills for a specific class, grouped by category, with starting LP (Learning Points) that determine how many skills the character can learn at creation. LP are class+category specific (`ClassCategoryLearningPoints` table).
**Special abilities** (`creation_rules.go`):
M5 allows rolling a W100 to gain a random special ability at character creation. The `GetSpecialAbilityByRoll(roll)` function maps dice outcomes to named bonuses (e.g., roll 56–60 → "Gute Reflexe+9"). This is pure backend logic; the frontend passes the rolled value as part of the creation session data, and the server calls this function when computing derived values.
**Dashboard integration:** `CharacterList.vue` shows in-progress sessions via `CharacterCreationSessions.vue`. Users can resume or delete draft sessions.
### 6.5 PDF Export Pipeline
**Flow (backend):**
```
ExportCharacterToPDF (pdfrender/handlers.go)
↓
LoadCharacterFromDB (full preload)
↓
For each template page (page1_stats.html, page2_play.html, ...):
→ Execute Go text/template with character data
→ chromedp: launch Chromium, navigate to data URL, print to PDF
→ Check <!-- MaxItems: N --> overflow marker
→ Generate continuation pages if needed (page1.2_stats.html)
↓
pdfcpu.MergeFiles → single merged PDF
↓
Save to cfg.ExportTempDir
↓
Return { filename: "CharName_20231225_143045.pdf" }
```
**Flow (frontend):**
```
ExportDialog.vue
↓
GET /api/pdf/templates → populate template selector
↓
User selects format (PDF / VTT / BaMoRT) + template
↓
For PDF format:
GET /api/pdf/export/:id?template=Default_A4_Quer
→ Response: { filename: "..." }
→ window.open(baseURL + /api/pdf/file/<filename>, '_blank')
For VTT format:
GET /api/importer/export/vtt/:id/file (blob) → browser download link
For BaMoRT format:
GET /api/transfer/download/:id (blob) → browser download link
```
**Note:** For PDF, `window.open` is called after the async API response, making it subject to popup blockers.
### 6.6 Audit Log
**Files:** `backend/character/audit_log.go`, `audit_log_handlers.go`
Every change to EP, gold, or significant character values writes an immutable `AuditLogEntry` record:
| Field | Purpose |
|-------|---------|
| `CharacterID` | Which character |
| `FieldName` | What changed (e.g., `"experience_points"`, `"goldstücke"`) |
| `OldValue` / `NewValue` | Before and after |
| `Difference` | `NewValue - OldValue` |
| `Reason` | Typed constant: `manual`, `skill_learning`, `skill_improvement`, `spell_learning`, `equipment`, `reward`, `correction`, `import` |
| `UserID` | Who made the change |
| `Notes` | Free-text context |
| `Timestamp` | Auto-set by GORM |
API endpoints:
- `GET /api/characters/:id/audit-log` — all entries or filtered by `?field=experience_points`
- `GET /api/characters/:id/audit-log/stats` — aggregated statistics
---
## 7. Data Access and Persistence
### Database Connection
- **Production/development:** MariaDB 11.4 via GORM MySQL driver. DSN from `DATABASE_URL` env var.
- **Tests:** SQLite (via CGO). `testutils.SetupTestDB()` copies `testdata/prepared_test_data.db` to a temp dir per test run, ensuring isolation.
- **Global variable:** `database.DB *gorm.DB` — shared across all packages by import.
### Schema Migrations
`models.MigrateStructure(db)` is called at startup and runs GORM `AutoMigrate` for all entity types in dependency order:
1. `game_systems`
2. GSMaster tables (skills, spells, equipment, weapons, containers, believes, misc lookups)
3. Character tables (chars, attributes, skills, spells, equipment sub-tables)
4. Equipment tables
5. Skill learning cost tables
6. Learning/cost relation tables
Migration history is tracked in `schema_version` and `migration_history` tables.
### Test Data
`testdata/prepared_test_data.db` is a pre-populated SQLite snapshot containing real test characters, including **character ID 18 ("Fanjo Vetrani")** which is used as the primary test fixture throughout all backend tests.
### Custom Types
`StringArray` is a custom GORM type that serializes `[]string` as JSON into a TEXT column:
```go
type StringArray []string
// Stored as: ["specialization1","specialization2"]
```
Used by `Char.Spezialisierung`.
---
## 8. Module Interaction Map
```
┌─────────────────────────────────────────────────────────────────────┐
│ Frontend (Vue 3) │
│ │
│ CharacterDetails ──────→ SkillView ──────→ SkillLearnDialog │
│ │ │ │
│ │ SpellView ──────→ SpellLearnDialog │
│ │ │ │
│ └──────→ ExportDialog │ │
│ │ │ │
└─────────────────────┼──────────────────────────────┼────────────────┘
│ REST API │ REST API
┌─────────────▼──────────────┐ ┌───────────▼───────────────┐
│ pdfrender module │ │ character module │
│ ExportCharacterToPDF │ │ GetLernCostNewSystem │
│ chromedp → Chromium │ │ LearnSkill / ImproveSkill │
│ pdfcpu merge │ │ Audit log writes │
└─────────────────────────── ┘ └───────────────────────────┘
│
┌────────────▼──────────────┐
│ gsmaster module │
│ Skill/Spell lookup │
│ Cost table queries │
└───────────────────────────┘
│
┌────────────▼──────────────┐
│ models package │
│ GORM entity definitions │
│ LearnCost, Char, etc. │
└───────────────────────────┘
│
┌────────────▼──────────────┐
│ database.DB │
│ MariaDB (prod/dev) │
│ SQLite (test) │
└───────────────────────────┘
```
**Cross-module dependencies (backend):**
- `character` depends on `gsmaster` (skill/spell lookup for cost calculations)
- `character` depends on `models` (all entity types)
- `character` depends on `database` (direct DB access)
- `gsmaster` depends on `models` and `database`
- `pdfrender` depends on `models` and `database` (loads full character)
- `maintenance` depends on `gsmaster`, `models`, `database`
- `user` is depended on by all modules via `AuthMiddleware` import into `router`
---
## 9. Complete API Route Reference
### Public Routes (no authentication)
```
POST /register
POST /login
POST /password-reset/request
GET /password-reset/validate/:token
POST /password-reset/reset
GET /api/public/version
GET /api/public/systeminfo
GET /api/pdf/file/:filename
```
### User Routes (authenticated)
```
GET /api/user/profile
PUT /api/user/display-name
PUT /api/user/language
PUT /api/user/email
PUT /api/user/password
```
### App System Routes
```
GET /api/version — version info (authenticated)
GET /api/systeminfo — system info (authenticated)
GET /api/public/version — version info (public, no auth)
GET /api/public/systeminfo — system info (public, no auth)
```
### Admin User Management (admin role required)
```
GET /api/users
GET /api/users/:id
PUT /api/users/:id/role
DELETE /api/users/:id
PUT /api/users/:id/password
```
### Character Routes
```
GET /api/characters — list own + shared characters
POST /api/characters — create character
GET /api/characters/:id — get full character (FeChar)
PUT /api/characters/:id — update character
PATCH /api/characters/:id — partial update
DELETE /api/characters/:id — delete (owner only)
PUT /api/characters/:id/image — update portrait
GET /api/characters/:id/datasheet-options — dropdowns for editing
GET /api/characters/:id/shares — list share grants
PUT /api/characters/:id/shares — update share grants
GET /api/characters/:id/available-users — users available for sharing
GET /api/characters/:id/experience-wealth — EP + wealth snapshot
PUT /api/characters/:id/experience — update EP
PUT /api/characters/:id/wealth — update wealth
GET /api/characters/:id/audit-log — change history
GET /api/characters/:id/audit-log/stats — audit statistics
POST /api/characters/lerncost-new — compute learning costs
POST /api/characters/lerncost — alias for lerncost-new
POST /api/characters/improve-skill-new — execute skill improvement
POST /api/characters/improve-skill — alias
POST /api/characters/:id/learn-skill-new — execute skill learning
POST /api/characters/:id/learn-skill — alias
POST /api/characters/:id/learn-spell-new — execute spell learning
POST /api/characters/:id/learn-spell — alias
POST /api/characters/available-skills-new — available skills with costs
POST /api/characters/available-skills — alias
POST /api/characters/available-skills-creation — skills for creation wizard
POST /api/characters/available-spells-creation — spells for creation wizard
POST /api/characters/available-spells-new — available spells with costs
POST /api/characters/available-spells — alias
GET /api/characters/spell-details — spell detail lookup
GET /api/characters/:id/reward-types — available reward types
GET /api/characters/:id/practice-points — PP by category
PUT /api/characters/:id/practice-points — update PP
POST /api/characters/:id/practice-points/add — add PP
POST /api/characters/:id/practice-points/use — consume PP
GET /api/characters/skill-categories — static skill category list
GET /api/characters/create-sessions — list wizard sessions
POST /api/characters/create-session — start new session
GET /api/characters/create-session/:id — get session data
PUT /api/characters/create-session/:id/basic — save step 1
PUT /api/characters/create-session/:id/attributes — save step 2
PUT /api/characters/create-session/:id/derived — save step 3
PUT /api/characters/create-session/:id/skills — save step 4
POST /api/characters/create-session/:id/finalize — create character from session
DELETE /api/characters/create-session/:id — discard session
GET /api/characters/races — available races list
GET /api/characters/classes — available character classes
GET /api/characters/classes/learning-points — LP per class+category for creation
GET /api/characters/origins — available origins
GET /api/characters/beliefs — belief/faith search
POST /api/characters/calculate-static-fields — derived values (no dice)
POST /api/characters/calculate-rolled-field — derived value requiring dice roll
```
### GSMaster Routes (read: all authenticated; write: maintainer+)
```
GET /api/maintenance — all master data
GET /api/maintenance/skills
GET /api/maintenance/skills-enhanced
GET /api/maintenance/skills/:id
GET /api/maintenance/skills-enhanced/:id
GET /api/maintenance/weaponskills[/*]
GET /api/maintenance/spells[/*]
GET /api/maintenance/equipment[/*]
GET /api/maintenance/weapons[/*]
POST/PUT/DELETE above (maintainer only)
```
### Maintenance Routes (maintainer role required)
```
GET /api/maintenance/gsm-believes
PUT /api/maintenance/gsm-believes/:id
GET /api/maintenance/game-systems
PUT /api/maintenance/game-systems/:id
GET /api/maintenance/gsm-lit-sources
PUT /api/maintenance/gsm-lit-sources/:id
GET /api/maintenance/gsm-misc
PUT /api/maintenance/gsm-misc/:id
GET /api/maintenance/skill-improvement-cost2
PUT /api/maintenance/skill-improvement-cost2/:id
GET /api/maintenance/setupcheck
GET /api/maintenance/setupcheck-dev
GET /api/maintenance/mktestdata
GET /api/maintenance/reconndb
GET /api/maintenance/reloadenv
POST /api/maintenance/transfer-sqlite-to-mariadb
```
### PDF Export Routes
```
GET /api/pdf/templates — list available templates
GET /api/pdf/export/:id — export character to PDF
POST /api/pdf/cleanup — clean up old generated PDF files
GET /api/pdf/file/:filename — download generated PDF (public, no auth)
```
### Importer Routes
```
POST /api/importer/upload — import VTT JSON + CSV
POST /api/importer/spells/csv — import spell CSV
GET /api/importer/export/vtt/:id — export as VTT JSON
GET /api/importer/export/vtt/:id/file — download VTT JSON file
GET /api/importer/export/csv/:id — export as CSV
GET /api/importer/export/spells/csv — export all spells as CSV
```
### Transfer Routes
```
GET /api/transfer/export/:id — export character JSON
GET /api/transfer/download/:id — download character JSON file
POST /api/transfer/import — import character JSON
POST /api/transfer/database/export — export full database
POST /api/transfer/database/import — import full database
```
---
## 10. Infrastructure and Deployment
### Development Environment
```
docker/docker-compose.dev.yml
bamort-backend-dev (port 8180) — Go source mounted + Air live-reload
bamort-frontend-dev (port 5173) — Vue source mounted + Vite HMR
bamort-mariadb-dev (port 3306) — MariaDB with health-check
bamort-phpmyadmin-dev (port 8081) — Database GUI
```
- Full source code is volume-mounted into each container.
- Backend uses `air -c .air.toml` for hot-reload on `.go` file changes.
- Frontend uses Vite's native HMR for instant module replacement.
- Database data persists in `docker/bamort-db-dev/` on the host.
- Database is initialized from `docker/init-db/*.sql` on first container creation only.
### Production Environment
```
docker/docker-compose.yml
bamort-backend (port 8182→8180) — compiled Go binary, no source mount
bamort-frontend (port 8181→80) — Nginx serving pre-built Vue bundle
bamort-mariadb (not exposed) — MariaDB accessible only within Docker network
```
- Backend image: multi-stage build. Stage 1 (golang:1.25-alpine) compiles the binary. Stage 2 (alpine:3.23) installs Chromium and copies only the binary + templates.
- Frontend image: multi-stage. Stage 1 (node:22-alpine) runs `npm run build` with `VITE_*` build args baked in. Stage 2 (nginx:alpine) serves the static bundle.
- **`VITE_API_URL`** is a **compile-time** build argument — runtime env vars cannot change it after image build.
- Database port is intentionally not exposed in production.
- TLS termination is expected at an external reverse proxy (e.g., Traefik).
- Templates are volume-mounted: `./templates:/app/templates`.
### Starting/Stopping
```bash
# Development
cd /data/dev/bamort
./docker/start-dev.sh # builds + starts all dev containers
./docker/stop-dev.sh # stops and removes dev containers
# Production
./docker/start-prd.sh # builds new images while old containers run, then switches
./docker/stop-prd.sh # stops production containers
```
---
## 11. User Roles and Access Control
| Capability | standard | maintainer | admin |
|-----------|----------|-----------|-------|
| Register / login | ✓ | ✓ | ✓ |
| View own characters | ✓ | ✓ | ✓ |
| View public/shared characters | ✓ | ✓ | ✓ |
| Create/edit/delete own characters | ✓ | ✓ | ✓ |
| Learn/improve skills and spells | ✓ | ✓ | ✓ |
| Export characters to PDF | ✓ | ✓ | ✓ |
| Import/export characters (JSON/CSV) | ✓ | ✓ | ✓ |
| Read GSMaster data | ✓ | ✓ | ✓ |
| Write GSMaster data | ✗ | ✓ | ✓ |
| Maintenance operations | ✗ | ✓ | ✓ |
| List all users | ✗ | ✗ | ✓ |
| Change user roles | ✗ | ✗ | ✓ |
| Delete users | ✗ | ✗ | ✓ |
| Reset any user's password | ✗ | ✗ | ✓ |
**Enforcement mechanisms:**
- Backend: `user.AuthMiddleware()` on all `/api/*` routes
- Backend: `user.RequireMaintainer()` middleware on maintenance write routes
- Backend: `user.RequireAdmin()` middleware on `/api/users/*` routes
- Backend: `checkCharacterOwnership()` inside character handlers (returns 403 if user doesn't own the character)
- Frontend: router navigation guard redirects non-admins away from `/users`
- Frontend: `isOwner` prop controls visibility of edit/delete buttons in `CharacterDetails`
---
## 12. Internationalisation (i18n)
**Implementation:** `vue-i18n` (v11, composition-mode `legacy: false`)
**Locales:** `src/locales/de/` and `src/locales/en/` — JS module files (not JSON) exporting translation objects. Both must be updated when adding new UI strings.
**Default language:** `de` (German)
**Language selection precedence:**
1. User's stored preference in `localStorage.language`
2. User's `preferred_language` field from their profile (set on `fetchCurrentUser()`)
3. Fallback to `de`
**Language change flow:**
- User changes language in `UserProfileView` → `PUT /api/user/language`
- Frontend immediately sets `this.$i18n.locale` and updates `localStorage.language`
- On next login, `userStore.fetchCurrentUser()` sets locale from profile
**Usage in components:**
```vue
{{ $t('skill.name') }} <!-- in template -->
this.$t('error.notFound') <!-- in script -->
this.$te('help.faq3.question') <!-- existence check for dynamic FAQ -->
```
---
## 13. Known Limitations and Security Notes
### Authentication Security
> **Important:** The current token scheme has cryptographic weaknesses.
1. **MD5 token generation** — MD5 is not a cryptographic authentication scheme. The token is derived predictably from `username + createdAt`, without a secret key. An attacker with knowledge of when a user registered could forge tokens.
2. **No token signature verification** — `CheckToken` extracts the user ID from the token string and loads the user from the database; it does not verify that the token was actually issued by the server.
3. **MD5 password hashing** — Passwords are hashed with MD5 (not bcrypt/argon2). MD5 is unsuitable for password storage; it is fast enough for brute-force attacks and not salted.
4. **Token scope** — Tokens do not expire. Once issued, a token is valid indefinitely.
The bcrypt implementation is commented out in `user/handlers.go` and `user/model.go` — migration to bcrypt for future versions is anticipated but not yet active.
### Other Notes
- `backend/startserver.sh` contains hardcoded development credentials — this file should not be committed to public repositories.
- The PDF download endpoint (`/api/pdf/file/:filename`) is unauthenticated by design (to allow direct browser downloads) but relies on filename unpredictability for security.
- `FileUploadPage.vue` manually adds an `Authorization` header that is already added by the Axios interceptor — this is a redundancy, not a security issue.
- The production `DATABASE_URL` in `docker-compose.yml` is constructed inline without fallback defaults — missing env vars will produce an empty credentials DSN.
Reference in New Issue Copy Permalink