ORBAT Designer

ORBAT Designer is a web-based application designed to facilitate the creation, management, and visualization of military Orders of Battle (ORBATs), specifically tailored for use with Digital Combat Simulator World (DCS World). It allows users to define equipment, create unit templates, and build hierarchical ORBATs using a drag-and-drop interface, with a focus on a template-driven, SPA-like experience.

I created this project because, as a mission and campaign designer for a large virtual squadron, I desired a tool that would allow me to rapidly create and manage complex ORBATs to help conceptualize enemy forces, manage group names in DCS World, and to provide markdown and graphical export of the ORBATs for use in mission briefings and campaign documentation (graphical export is not yet implemented).

Main Interface

The main ORBAT Designer interface showing the drag-and-drop canvas, echelon palette, and unit details panel

Features

Core ORBAT Building

• Drag-and-drop interface for building military unit hierarchies
• Schema-based validation ensures realistic military organizational structures
• Unit management with editable names, locations, and personnel counts
• Equipment assignment supporting both individual items and standardized equipment sets
• Real-time DCS group string generation following proper naming conventions

Template and Schema System

• Echelon schemas define military hierarchy rules and parent-child relationships
• User-created templates for reusable organizational patterns
• Equipment sets for standardized loadouts (e.g., "Tank Company Set")
• Schema switching to work with different military force structures

Data Management

• Save and load ORBATs with full unit trees and equipment assignments
• Multi-format export (YAML, JSON, Markdown)
• Template sharing and import/export capabilities
• User preferences with theme and display settings

Equipment Management

• Comprehensive equipment database populated from DCS World data
• Equipment filtering by type, category, and tags
• Custom naming for individual equipment items (useful for ship names, callsigns)
• Visual equipment indicators displayed as badges on units

DCS World Integration

• Automatic group naming with configurable schema prefixes

Aspirations:

• Graphical export of ORBATs for use in mission briefings and documentation
• DCS World lua export to allow for constituent equipment sets to be defined directly in a user's templates file.

1. Tech Stack

The ORBAT Designer project utilizes the following technologies and tools:

Main Application

• Frontend Framework: Remix
• Language: TypeScript
• UI Components: shadcn/ui
• Icons: Lucide Icons
• Database: SQLite
• Containerization: Docker
• CSS: Tailwind CSS
• Build Tool: Vite

Data Pipeline

• Language: Python
• Project Manager: uv

CI/CD

• CI/CD: GitHub Actions
• Task Runner/Build Tool: Taskfile

2. Getting Started

Currently, the only way to run ORBAT Designer is to locally host a Docker container.

With Docker installed, you can run the following command to pull and start the container with a persistent data volume:

# Use the latest stable release with persistent data
docker run -d -p 3000:3000 -v orbat-designer-data:/app/data --name orbat-designer ghcr.io/yolowingpixie/orbat-designer:latest

# With auto-restart on boot
docker run -d -p 3000:3000 -v orbat-designer-data:/app/data --name orbat-designer --restart unless-stopped ghcr.io/yolowingpixie/orbat-designer:latest

# To stop the container
docker stop orbat-designer

# To start it again
docker start orbat-designer

Build from Source

Alternatively, you can build the application from source.

1. Clone the Repository:

   git clone https://github.com/yolowingpixie/orbat-designer.git
   cd orbat-designer

2. Install Dependencies:

   task init

3. Start the Development Server:

   task dev

4. Build the docker container and run it:

   task docker:compose:up

5. Stop the container:

   task docker:compose:down

3. Development and Contributing

Refer to the following documents for detailed project information:

• /docs/prd.md (Product Requirements Document)
• /docs/domainmodel.md (Domain Model)
• /docs/datamodel.md (Data Model)

Key Directories

• app/: Contains the core application code (routes, components, hooks, utilities).
• prisma/: Contains database schema definitions, templates and migration files.
• public/: Static assets.
• tools/: Currently contains data pipeline to transform Quaggles' DCS Lua Datamine into a format that can be used to populate the database.
• Taskfile.yml: Defines all Taskfile tasks.

Common Development Tasks

This section outlines the initial setup and common tasks a developer will perform. All tasks are run using task <task-name>.

1. Clone the Repository:

   git clone <repository-url>
   cd orbat-designer

2. Prerequisites:

   • Ensure Docker is installed and running.
   • Ensure Taskfile is installed.
   • Ensure Node.js (LTS version recommended) and npm are installed.

3. Initial Project Setup: This command installs npm dependencies, sets up the SQLite database using Prisma migrations, and potentially seeds the database with default data.

   task init

4. Start the Development Server: This command starts the Remix development server, usually on http://localhost:3000.

   task dev

5. Linting and Formatting:

   • To check for code style and potential errors:

     task lint

   • To automatically format the codebase:

     task format

6. Running Tests:

   • To run all unit and integration tests:

     task test

   • To run tests in watch mode:

     task test:watch

   • Get coverage report:

     task test:coverage

7. Database Tasks (using Prisma):

   • To generate the Prisma Client after schema changes:

     task db:generate

   • To apply migrations to development database:

     task db:migrate:dev

   • To apply migrations to production database:

     task db:migrate

   • To seed the database with initial data:

     task db:seed

   • To reset database and reapply all migrations:

     task db:reset

   • To check database health and migration status:

     task db:health

   • To open Prisma Studio for database inspection:

     task db:studio

8. Building for Production: This command runs typecheck, lint, and tests before building the application.

   task build

9. Version Management:

   • Show current version:

     task version:show

   • Bump patch version (bug fixes):

     task version:patch

   • Bump minor version (new features):

     task version:minor

   • Bump major version (breaking changes):

     task version:major

10. Running with Docker (Local Production Preview):

    • To build the Docker image (includes full build):

      task docker:build

    • To run the built image (with persistent data):

      task docker:start

    • To stop the running container:

      task docker:stop

    • To view container logs:

      task docker:logs

    • To test Docker setup with health checks:

      task docker:test

11. Docker Compose (Alternative):

    • To start with Docker Compose:

      task docker:compose:up

    • To stop with Docker Compose:

      task docker:compose:down

12. CI Tasks

    • Run full CI pipeline:

      task ci

    • Quick quality check:

      task qa

    • Check typecheck and lint only:

      task check

    • Auto-fix linting and formatting:

      task fix

    Volume Management:

    • Create the data volume manually:

      task docker:volume:create

    • Inspect the volume:

      task docker:volume:inspect

    • Remove the volume (⚠️ this deletes all user data):

      task docker:volume:remove

    • Show Docker Compose volume information:

      task docker:compose:volumes

    Additional Tasks:

    • Check health of running container:

      task docker:health

    • Clean build artifacts and caches:

      task clean

    • Clean all caches (npm, eslint, etc.):

      task clean:cache

For a full list of available tasks and their descriptions, run:

task --list

Continuous Integration

The CI pipeline is defined in the .github/workflows directory at ci.yml.

Passing Requirements:

• Typecheck must pass
• ESLint must pass
• Unit tests must pass
• Code Coverage must beat the following thresholds (%):

      thresholds: {
        lines: 20,
        functions: 45,
        branches: 85,
        statements: 20,
      },

• Docker container must be able to be built in both:
  • linux/amd64
  • linux/arm64
• npm audit must find no vulnerabilities