andreapavoni/parabellum
41.9
Weak · 9 November 2026
59.6k
lines of production code
Rust
with TypeScript
7
measurements over time
What this system is
Parabellum is a Rust-based MMORPG backend that implements a CQRS and Event Sourcing architecture to manage complex game state, including villages, armies, and heroes. It exposes a JSON API for authentication, game context retrieval, and building management, while maintaining data consistency through synchronous projectors and supporting operational tasks like event replay and data backfilling. The system is paired with a Preact frontend that handles client-side routing and UI rendering for the game interface.
How it got here
2024–2025 — Workspace refactoring and core game systems
15 changes.
The project underwent a major structural overhaul, migrating from a single crate to a multi-crate Rust workspace and adopting a CQRS/Event Sourcing architecture. This period focused on rebuilding the core domain models, implementing a comprehensive battle system with hero integration, and establishing secure token-based API authentication for both the backend and the new Preact frontend.
2026 — CQRS migration and API modernization
5 changes.
The project migrated the village infrastructure to a CQRS and Event Sourcing architecture, introducing event stores, projectors, and operational CLI tools for data management. Simultaneously, the web layer was modernized with a new Axum-based JSON API and an SPA frontend serving mechanism to replace the previous backend setup.
Features
Adds structured logging with console and daily rotating file output
The server now initializes a structured logging system using \tracing\_subscriber\ that outputs logs to both the console and a daily rotating file (\logs/parabellum.log\). Log verbosity is controlled by the \RUST\_LOG\ environment variable, defaulting to \info\ for most crates and \warn\ for infrastructure components like \tower\_http\ and \sqlx\ to reduce noise during normal operation.
_parabellum\server/src · high confidence
Expanded game domain models for villages, armies, and heroes
The \parabellum\_game/models\ directory now contains comprehensive domain models for core game entities. The \village.rs\ model defines village structure including buildings, armies, reinforcements, and culture points, while \army.rs\ manages troop compositions, hero attachments, and combat statistics. A new \hero.rs\ model introduces hero attributes, experience, and resource focus bonuses. Additional models include \culture\_points.rs\ for village expansion costs, \marketplace.rs\ for player trade offers, \trapper.rs\ for defensive trap mechanics, \smithy.rs\ for unit upgrade costs, and \map.rs\ for terrain generation. The \buildings.rs\ file was refactored to integrate with these new types and handle building constraints and production values.
_parabellum\game/models · high confidence
Frontend rewritten in Preact with new UI components and routing
The frontend application has been rebuilt using Preact, replacing the previous implementation. This change introduces a new client-side routing system (via \@/lib/router\), a centralized authentication session hook (\useAuthSession\), and a comprehensive set of UI components including \Layout\, \ArmyTable\, \BuildingSprite\, and \ResourceFieldsMap\. The new interface supports features such as village switching, building queue management with cancellation, and a hex-based resource field map, all driven by TanStack Query for data fetching and caching.
frontend/src · high confidence
Initial domain type definitions for game entities and logic
This change introduces the core type definitions for the game's domain model within the \parabellum\_types\ crate. It defines the structural data for military units (including stats, costs, and roles for various tribes), buildings, and resources. It also establishes the data structures for battle reports, scouting outcomes, and player/user entities, providing the foundational types required for game state management and reporting.
_parabellum\types · high confidence
Initial project scaffolding and developer environment setup
The repository has been initialized with the foundational structure for the Parabellum MMORPG, including a Rust backend and a Preact frontend. This change introduces the necessary configuration files to support local development and containerized deployment, such as a Dockerfile, docker-compose files for development and production, and a .env.sample with default settings for PostgreSQL and server ports. It also adds build tooling configurations (Justfile, Vite, Bun, Tarpaulin) and standard project documentation (README, LICENSE, Code of Conduct) to enable contributors to set up the database, run the application, and execute tests.
(repo-wide) · high confidence
Introduce token-based API authentication and HTTP server
The web layer now supports user authentication via short-lived JWT access tokens and opaque refresh tokens, replacing previous session mechanisms. This change introduces the \AuthTokenService\ for issuing and verifying tokens, registers authentication endpoints (\/auth/token/login\, \/register\, \/logout\, \/refresh\) in the Axum router, and integrates token verification into the request handling pipeline to establish a \CurrentUser\ context for subsequent API calls.
_parabellum\web · high confidence
New CLI tools for event replay, data backfilling, and seeding
The server distribution now includes three new command-line utilities to support operational tasks. The \parabellum\_replay\ tool allows administrators to replay event-sourced state changes (with an optional snapshot rebuild) to fix data inconsistencies or migrate schemas. The \parabellum\_backfill\_heroes\ utility detects and repairs missing hero entities and broken army links for existing players, supporting a dry-run mode for safety. Additionally, \parabellum\_seed\ enables the population of the database with initial test data from JSON configuration files.
_parabellum\server/bin · high confidence
New JSON API for authentication, game state, and building management
The web layer now exposes a structured JSON API (powered by Axum and utoipa) to replace the previous backend/frontend setup. This API provides endpoints for user authentication (login, register, token refresh, logout), game context retrieval (village lists, map regions, reports, player profiles), and building management (detailed building views, training, upgrades, downgrades, and construction cancellation). It also includes handlers for troop movements (attacks, scouts, reinforcements, resource sends) and marketplace operations, with DTOs designed for a Preact frontend.
_parabellum\web/api · high confidence
New battle system with hero integration and detailed reporting
The game logic now includes a comprehensive battle engine that calculates combat outcomes, including troop losses, survivor counts, and building damage. A key addition is the integration of heroes into combat, where they provide offensive and defensive bonuses, gain experience, and can be killed or survive battles with specific health states. The system also tracks loyalty changes, scouting reports, and trap outcomes, providing a detailed report of each engagement.
_parabellum\game · high confidence
SPA frontend serving and health check API
The web layer now serves a Single Page Application (SPA) via a new HTML shell that dynamically injects Vite-generated asset tags (CSS and JS modules) based on the frontend manifest, replacing previous static asset handling. A dedicated health check endpoint is exposed at the root to return a simple 'ok' status, and the SPA fallback route ensures client-side routing works by returning the shell for non-asset paths.
_parabellum\_web/templates, parabellum\web/web · high confidence
Removals
Removal of legacy entry points and module declarations
The \src/lib.rs\ and \src/main.rs\ files have been deleted, removing the previous \pub mod game\ declaration and the default "Hello, world!" main function. This indicates a structural cleanup where the initial scaffolding or legacy entry points are no longer part of the application's build or public API.
src · high confidence
Removal of legacy game domain models
The \src/game\ module has removed the previous implementations of core game entities, specifically deleting the files for Army, common types (Tribe, ResourceGroup, SmithyUpgrades), Map fields (Valley, Oasis, Position), and Village. This cleanup eliminates the old data structures and logic for unit composition, map topology, and village management, likely as part of a broader refactoring or migration to a new architecture.
src/game · high confidence
Architecture
Application layer restructured around CQRS/ES with new identity and session management
The \parabellum\_app\ crate has been reorganized to support a Command-Query Responsibility Segregation (CQRS) and Event Sourcing (ES) architecture. This introduces a central \GameApplication\ facade that orchestrates gameplay use cases, alongside dedicated modules for identity management (including user registration, password hashing with Argon2, and JWT-based refresh session lifecycle) and a scheduler for processing due game actions. New application services and ports have been added for map reads, player population leaderboards, and village operations (buildings, development, heroes, marketplace, movements, and traps), providing a structured entry point for the HTTP layer while decoupling application logic from infrastructure persistence.
_parabellum\app · high confidence
Migrate village infrastructure to CQRS/Event Sourcing architecture
The \parabellum\_infra\ layer has been restructured to support a CQRS and Event Sourcing pattern. This introduces a typed error boundary (\cqrs\_errors.rs\) that maps internal CQRS errors to application-level errors, and a new \VillageEsAdapter\ that implements application ports by delegating to an Event Store service. Read-model consistency is now maintained via synchronous projectors (\VillageProjector\ and \ReportProjector\) that consume domain events to update Postgres tables for villages, armies, movements, and reports. The infrastructure also includes a PostgreSQL connection pool manager and an advisory lock mechanism to handle concurrent access safely.
_parabellum\infra · high confidence
Behavioural changes
Added .gitkeep file to frontend/assets directory
A .gitkeep file has been added to the frontend/assets directory to ensure the folder is tracked by version control even when empty, preventing the directory from being ignored or removed by git.
frontend/assets · high confidence
Database schema evolution for game mechanics and architecture
The database schema has been updated to support the core game systems and architectural changes. Initial migrations established the foundation with user/player tables and later introduced a CQRS/Event Sourcing structure, adding tables for villages, armies, heroes, map fields, and event snapshots. Subsequent changes refined authentication by creating a dedicated refresh session table and retargeting its foreign key to the village table. Game logic updates include adding a 'trapped' state for armies and tracking trap counts in villages, introducing a 'canceled' status for scheduled actions, and adding an attempt counter to the scheduled actions table to improve reliability.
migrations · high confidence
Introduction of structured error types for application, database, and game logic
The \parabellum\_types/errors\ module now defines three distinct error enums—\AppError\, \DbError\, and \GameError\—to provide specific, user-facing feedback for various failure scenarios. \AppError\ handles infrastructure and logic issues such as optimistic concurrency conflicts, authentication failures, and queue limits. \DbError\ maps database-specific failures, including not-found states for villages, users, armies, heroes, and marketplace offers, as well as transaction and JSON parsing errors. \GameError\ encapsulates domain rule violations, covering resource shortages, building constraints (such as tribe mismatches, capital restrictions, and level limits), hero management (revival, ownership, and attribute limits), troop movement cancellation windows, and marketplace validity. This structure ensures that errors are clearly categorized and descriptive for both internal debugging and external API responses.
_parabellum\types/errors · high confidence
Test coverage
Added integration tests for web API authentication and game context; Added tests for building overview use case.
Dependencies
Project restructured into a Rust workspace with upgraded dependencies and new frontend tooling
The project has been refactored from a single crate into a multi-crate Rust workspace (parabellum\_game, parabellum\_app, parabellum\_infra, parabellum\_server, parabellum\_types, parabellum\_web), raising the minimum Rust version to 1.95 and the edition to 2024. Key dependency upgrades include axum (0.6 to 0.8), sqlx (0.8), rand (0.8.5 to 0.10), and tower-http (0.3 to 0.6), alongside the addition of a new frontend package.json using Vite, Preact, and Tailwind CSS. The Cargo.lock file was removed as dependency resolution is now managed by the workspace.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 40 → 42 (+1.6)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 65 → 65 (+0.0)
- Architecture 87 → 86 (-0.8)
- Maturity 50 → 69 (+18.4)
- Readiness 27 → 28 (+1.4)
- Security 46 → 45 (-1.0)
- Domain Modelling 100 → 100 (+0.0)
- Event Sourcing 100 → 100 (+0.0)
- Accessibility 45 → 45 (-0.2)
- Performance 100 → 100 (+0.0)
Resolved (8)
- Complete duplication of Refresh Session management logic. GameApplication exposes every single method from RefreshSessionUseCases with identical signatures (except for the implicit 'self' context). This makes the Use Case layer redundant and violates the separation of concerns. The Application layer should not expose the internal mechanics of session management directly.
- Same duplication issue as above, but for Player entities. The Application layer exposes two distinct lookup methods for Player that mirror the Port and Repository layers exactly. This violates the principle of the Application layer being a coordinator rather than a pass-through for data access. It also creates a tight coupling between the Application interface and the underlying data model's indexing strategy.
- Scanner failed to run — not a clean result
- Scanner failed to run — not a clean result
- Severe duplication of identity lookup operations across three layers (Application, Port, Repository) with inconsistent naming conventions. The Application layer uses 'get_user_by_*', the Port layer uses 'get_user_by_*', but the Repository layer uses 'get_by_*'. Furthermore, the Application layer exposes low-level repository-style queries directly, bypassing the Use Case pattern for simple lookups, while other operations (like registration) go through Use Cases.
- Split parabellum_app
- Split parabellum_infra
- The GameApplication exposes raw map queries with positional parameters (x, y, radius) directly, while the MapUseCases layer expects structured Request objects. This inconsistency suggests that GameApplication is acting as a facade that duplicates the functionality of MapUseCases but with a less flexible, parameter-heavy signature. It also forces callers to construct coordinate logic that might be better handled by the use case layer.
New (1)
- Projects may be oversized for their cohesion
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
andreapavoni/parabellum was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 9 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 3c1cfccbdb37a2881e49b49246d46bf55099cf9d — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-bb0cb800cd0f.