Arcogine

Arcogine is a deterministic simulation engine for factory systems, economic dynamics, and agent-driven decision making.

What is Arcogine?

Arcogine is a simulation-first platform where you experiment with how pricing, capacity, and automated agents interact in a factory environment. Three systems feed back into each other:

     You set a price
           │
           ▼
    Demand responds        (lower price → more orders)
           │
           ▼
    Factory produces        (machines process jobs through routing steps)
           │
           ▼
    KPIs update             (throughput, lead time, backlog, revenue)
           │
           ▼
    You (or the agent)      (observe KPIs, decide what to change)
    make decisions
           │
           └───────────────► loop repeats

The simulation is fully deterministic: same inputs produce identical outputs every time. This makes it useful for comparing strategies, testing hypotheses, and understanding cause-and-effect in complex operational systems.

New to Arcogine? Read Concepts to understand what you're looking at before running your first session.

Quick start

Dev container (recommended)

git clone https://github.com/alaiba/arcogine.git
cd arcogine

Open the folder in VS Code with the Dev Containers extension. The container automatically installs Java 25, Gradle, and UI dependencies.

After the container is ready, start the UI and API in two terminals:

# Terminal 1: UI dev server
cd ui && npm run dev

# Terminal 2: Build and run API server
cd java && ./gradlew :sim-cli:bootJar --no-daemon
java -jar sim-cli/build/libs/arcogine.jar serve --addr 0.0.0.0:3000

Then open http://127.0.0.1:5173.

Other setup paths

• Docker Compose: cp .env.example .env && docker compose up --build

Your first session

You can go from clone to meaningful results in under five minutes:

1. Load a scenario — the welcome overlay offers three built-in options.
2. Run the simulation — click Run and watch KPIs update in real time.
3. Try an intervention — change the price or toggle a machine offline.
4. Save a baseline — snapshot the current state before a big change.
5. Compare — make the change, then compare against your baseline.
6. Toggle the agent — enable the Sales Agent and see how it manages pricing.

Built-in scenarios

Scenario	Challenge	What you'll learn
Basic	None — balanced factory	How the controls work and what the KPIs mean
Overload	Demand exceeds capacity	How to stabilize backlog and lead times with pricing
Capacity Expansion	Same pressure, more machines	Whether structural upgrades beat tactical tuning

Headless mode

Run a scenario without the UI:

java -jar java/sim-cli/build/libs/arcogine.jar run examples/basic_scenario.toml

Technology stack

Layer	Technology
Simulation engine	Java 25 (records, sealed interfaces, pattern matching)
HTTP API	Spring Boot 3.4 + Spring MVC
CLI	Picocli
Build	Gradle 8 (Kotlin DSL)
Frontend	React 19 + TypeScript + Vite
Container	Eclipse Temurin 25 JRE

Documentation

Document	What it covers
Concepts	How the simulation works, KPIs, agents, scenarios
API Reference	Every HTTP endpoint with curl examples
Architecture	Design philosophy, module structure, determinism contract
Full docs index	Everything else: testing, standards, vision, security

Quality gates

make             # show all available targets
make quality     # fast gates: compile, tests, coverage, lint, build
make quality-full  # everything: quality + Playwright E2E + Docker smoke + security scans

See TESTING.md for the full test category reference.

Contributing

See CONTRIBUTING.md for setup paths, development workflow, code style, and testing conventions.

License

Apache-2.0 — see LICENSE.