AI Business Simulation Platform by Maxim KushnirAI Business Simulation Platform by Maxim Kushnir

AI Business Simulation Platform

Maxim Kushnir

Completed work

AI Engineer

Cloud Infrastructure Architect

Software Engineer

AWS

Python

Rust

Artificial Intelligence

An AI-driven business simulation platform built on a deterministic simulation kernel.

Decisions in, audited consequences out — every number reproducible, every AI contribution bounded.

1. Executive Summary

Ventute is a decision-simulation engine for business. A user founds and operates a company inside a living economic world — setting prices, hiring, raising capital, managing supply chains, entering foreign markets, and answering to stakeholders — and each turn resolves into a fully-audited financial and operational outcome.

The hard problem in this space is trust. Most "AI business games" let a language model invent the numbers: the revenue, the cash balance, the market reaction. That is entertaining and worthless — the outputs are unreproducible, the accounting doesn't close, and there is nothing to learn from because the "consequences" are improvisation.

Ventute is architected around the opposite principle:

A deterministic kernel owns state, time, money, and legality. AI contributes only typed, capped, seeded judgment coefficients and post-hoc narrative. Nothing AI-generated reaches state except through a validated command or a range-capped judgment.

The result is a simulation that behaves like an institutional system of record: the accounting identity holds every turn, share counts are conserved, cash is never conjured, and any historical turn can be replayed bit-for-bit from its event log. AI makes the world feel alive and reactive — it never makes the world lie.

The platform ships as a production web application with 26 localizations, a professional "cockpit" UI, a business/education/enterprise entitlement model, LTI grade-sync for classrooms, and a full security, privacy, and compliance surface.

2. Core Capabilities & Features

Simulation core

Deterministic kernel — the single writer-of-record for state, time, money, and legality. A command registry is the only door to state; an append-only event reducer is pure (takes no context), which is what makes replay bit-exact.

Event-sourced turns — nondeterminism (RNG, AI judgment, clock reads) happens once, at command resolution, and is captured into emitted events. fold(events) reconstructs any state exactly.

Bitemporal world model — a lazily-evaluated economic world with checkpoints, world events, policy regimes, and difficulty tuning that "catches up" state on demand rather than ticking every entity.

Invariants as law — double-entry accounting identity, share conservation, and value-range guards are enforced inside the turn, not asserted after it.

Business engines (24+, phase-ordered)

A breadth of independently-modelled disciplines, each a small unit that proposes typed deltas to the kernel:

Domain Engines Macro / International FX, inflation, tariffs, foreign tax, hedging, macro events, jurisdiction Market demand (constant-elasticity multi-product), microeconomics (segments + WTP), marketing funnel (9 channels, 4Ps, B2B pipeline), competitor reaction Operations 7 operating models, capacity that bites, quality, logistics, supply chain (suppliers, POs, inventory, COGS) Finance corporate finance (debt/equity/capital budgeting), payroll, tax, accounting ledger (double-entry) Org / People hiring & lifecycle, culture, change management, compliance, benefits Governance / Long-horizon ESG (7 stakeholders), ethics, entrepreneurship (lean BML, R&D, VC/board), strategy Business models SaaS metrics, marketplace, manufacturing, contract/services (PSA), franchise Reporting MIS/BI, forecasting, decision science, statistics lab

AI agents & the judgment boundary

Typed, capped, seeded judgments — AI returns coefficients within declared ranges with justifications; it never authors an amount. A stubbed/recorded judge is used in tests for zero live calls.

Tiered, privacy-aware provider routing — business simulations route only to "secured" official providers (Anthropic, OpenAI, Google, xAI, Mistral) that offer a DPA and do not train on API data.

Circuit-breaker failover across providers, per-request timeouts, and a hard block on restricted-origin models on every path (including BYOK).

AI personas, advisors, and boardroom counterparts — mentors, an advisory board, negotiation and board-meeting counterparts — all reading a projected view of state, never writing it.

AI governance suite — red-team harness, engine-version compare, nightly eval packs, and an AI quality dashboard.

Data generation & analytics

Projection / read layer — a single component builds every tab payload from state, so the UI and AI prompt read a consistent, contract-defined view.

Native Monte-Carlo forecast engine — an optional Rust (PyO3 + rayon) extension runs parallel forward rollouts of the deterministic economy model for probabilistic forecasts.

Trust protocol — per-turn receipts, an evidence/provenance graph, a realism checker, and redaction before export.

User & institutional workflows

Solo, timed, and team (multiplayer-staged) turns; branch/counterfactual exploration.

Education & enterprise — cohorts, instructor groups, rubrics, grading exports, benchmark cohorts, LTI 1.3 grade sync, SSO, and an org console with audit logging.

Professional cockpit — two-level dashboard, exec briefing, risk register, operating plan, board pack, and a mobile-native bottom-nav layout.

Community, help center, methodology & status pages, GDPR self-service, and a demo mode that renders the real cockpit against scripted data.

3. Tech Stack & Architecture

Stack

Layer Technology Backend Python 3.11, FastAPI, Pydantic v2, async SQLAlchemy + asyncpg, Alembic Database PostgreSQL (managed via Neon in production) Cache / counters Redis (rate-limit & captcha counters shared across workers) Native compute Rust (ventute_sim, PyO3 + rayon) — optional Monte-Carlo forecast extension Frontend React 18, Vite 6, Zustand, React Router 6, Recharts, Tailwind CSS i18n i18next — 26 locales with full coverage AI providers Anthropic, OpenAI, Google Gemini, xAI, Mistral (secured set) + OpenRouter (BYOK/free) Observability structlog (JSON), Sentry (opt-in), PostHog (opt-in), OpenTelemetry-ready Runtime uvicorn (multi-worker), slowapi rate limiting, GZip

Footprint: ~104K LOC backend across 389 modules · 476 API endpoints · 41 Alembic migrations · 179 backend test modules · ~46K LOC frontend across 40 routes · 26 test suites.

Request & turn data flow

Browser (React SPA, Cloudflare Pages)
        │  HTTPS + JWT (httpOnly cookies)
        ▼
Edge (Cloudflare) — WAF, Turnstile, X-Origin-Verify injection
        │
        ▼
FastAPI (api.ventute.com)
   layered middleware: request-shape limits · security headers · ingress trust · rate limiting · CORS
        │
        ▼
POST /api/games/{id}/turn(/stream)
        │
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│  TURN PIPELINE                                                        │
│                                                                      │
│  INTENT   player free-text / typed action → typed intent            │
│    │                                                                 │
│  KERNEL   deterministic writer-of-record (state·time·money·legality) │
│    │      command registry → pure event reducer → invariants        │
│    │                                                                 │
│  ENGINE ORCHESTRATOR  phase-ordered graph (reads / owns / depends_on)│
│    macro → market → ops → finance → org → reporting                  │
│    │                                                                 │
│  AI JUDGMENT BOUNDARY  typed · capped · seeded coefficients only     │
│    │                                                                 │
│  PROJECTION / READ    one place builds every tab payload + AI prompt │
│    │                                                                 │
│  AUDIT    event log · turn receipt · evidence graph · observability  │
└─────────────────────────────────────────────────────────────────────┘
        │
        ▼
PostgreSQL (event log, turns, world checkpoints, ledgers) · Redis (counters) · S3/R2 (backups, artifacts)

The AI provider is called inside the judgment boundary and again for post-hoc narrative — it observes a projected, redacted view of state and returns only bounded coefficients or prose. It is never a writer.

4. Design Philosophy & Code Consistency

The repository is governed by a small number of load-bearing rules, maintained in the internal architecture documentation.

One writer of record. The kernel is the only path to state. Engines propose typed deltas; they do not mutate state directly. AI proposes coefficients; it does not touch numbers.

Determinism is a property, not a hope. All nondeterminism is injected (Clock, seeded Random) and captured at resolution time. The reducer is pure. Replay re-folds recorded events with zero recomputation → identical state. A golden/determinism test suite guards this.

Wiring is declared data, not call order. Engines declare phase, the state slices they reads/owns, and their depends_on. Run order is derived by topological sort. Two whole classes of bug — dependency cycles and two engines writing the same slice — are caught at registration, not three phases later mid-turn.

Decoupled services, module-per-concern. The service layer is split by domain (AI, game, world, memory, billing, enterprise, integrations, education, platform, accounts, admin). Integrations degrade to no-ops when their key/package is absent — the same optional-import pattern everywhere.

Progressive delivery via flags & kill switches. Product-affecting changes ship behind reversible feature flags; trust-critical paths are never flag-gated. Enrichment AI has a single kill switch that degrades to deterministic defaults under cost/incident pressure.

Strangler, not big-bang. The kernel was grown alongside the legacy turn loop and progressively adopts its responsibilities (pricing, payroll, supply, demand are already kernel-owned), each step golden-gated.

Contracts are versioned. Events, ledgers, judgments, and state are versioned Pydantic contracts; state carries a version and migrates forward.

6. Production, Security & Compliance

Deployment architecture

The production topology decouples the SPA, the API, and stateful backing services:

Component Production home Notes SPA (ventute.com) Cloudflare Pages VITE_* build vars baked at build time API (api.ventute.com) Container host (Fly.io / Render) multi-worker uvicorn Database Neon (managed Postgres) pooled DATABASE_URL, TLS required, connection tuning per-worker Cache / counters Upstash / Fly Redis shared rate-limit & captcha state across workers Object storage AWS S3 / Cloudflare R2 pg_dump backups + presigned runtime artifacts Secrets AWS SSM Parameter Store (optional) SecureStrings hydrated into env at startup Edge Cloudflare WAF, Turnstile, origin lock-down header

Containerisation (documented capability)

The repository ships production-grade, portfolio-quality Docker profiles (docs/docker.md). Whether or not a given deployment uses them, they encode the standard the artifacts are held to:

Multi-stage builds — the compiler/toolchain never ships to the runtime image (Dockerfile.prod builder → runtime for the backend; node-build → nginx-serve for the frontend).

Non-root runtime — backend runs as appuser (uid 10001); the frontend serves via unprivileged nginx workers — shrinking the blast radius of a container escape.

Static SPA on nginx — no Node runtime in the frontend image; SPA fallback, gzip, immutable-asset caching, and security headers.

Healthchecks so an orchestrator self-heals; small build contexts via .dockerignore (no venv, node_modules, tests, .env, or .git in the image); secrets from the environment, never baked in.

Managed DB, not a sidecar container — Postgres is Neon; the container only holds DATABASE_URL.

The prod Dockerfiles are exactly what a container host builds and runs, so the profile doubles as a local prod rehearsal and the deploy artifact. docker compose -f docker-compose.prod.yml up --build runs the full prod-shaped stack locally.

AWS integration

Two AWS seams are wired:

SSM Parameter Store (SSM_ENABLED=true) — on startup, every SecureString under SSM_PREFIX is pulled into the process environment, so production secrets live in SSM (Standard tier) rather than in files or the platform env; only a handful of bootstrap keys remain in the platform. See docs/secrets_ssm.md.

S3 object storage (S3_BACKUP_BUCKET, ARTIFACT_BUCKET) — automated pg_dump backups are pushed to every configured destination, and GDPR/audit exports are served as presigned URLs. Credentials fall back to the shared AWS_* pair; an R2 endpoint can be substituted for S3. See docs/object_storage.md.

Security posture

Security is treated as a layered discipline rather than a feature list. The summary below describes the posture — the categories of control and the outcomes they guarantee. Exact mechanisms, thresholds, header contracts, and configuration are deliberately kept out of this public document and live in access-controlled internal runbooks.

Authentication & sessions — short-lived signed access tokens with rotating refresh, delivered over hardened httpOnly/Secure cookies; modern memory-hard password hashing; optional federated sign-in and second-factor (TOTP) authentication.

Abuse & bot resistance — managed edge challenge (Turnstile), distributed per-endpoint rate limiting, additional throttles on sensitive flows, and anomaly tracking on authentication attempts.

Ingress trust — the app treats client-supplied network metadata as untrusted and derives identity only from infrastructure it controls, with an optional edge-attestation layer so the origin cannot be reached around the perimeter. Request-shape limits guard against resource-exhaustion vectors.

Transport & headers — strict CORS, host allowlisting, and a full security-header policy across the API and the static SPA.

Secrets — provider and per-tenant credentials are encrypted at rest; startup refuses to boot on weak or placeholder critical secrets; production secrets are sourced from a managed secret store, never from the repository or images.

AI data governance — regulated (business) workloads route only to providers under a data-processing agreement that do not train on submitted data; models of restricted origin are refused on every path.

Responsible disclosure: security issues should be reported privately to the maintainers, not filed as public issues. This README intentionally omits exploitable operational detail.

Compliance & data handling

GDPR self-service — dedicated data export and erasure endpoints, backed by a documented privacy review.

Consent-gated telemetry — Sentry and PostHog are opt-in and no-op without keys/consent; an in-DB funnel works without any third party.

Enterprise audit — org-scoped audit logging, rubrics, and benchmark cohorts (min k to prevent de-anonymization); LTI 1.3 grade sync for institutional integrity.

Clean legal & billing posture — legal/privacy/terms pages with honest disclosures (IP, indemnity, no monitoring, AI-Act notice). The platform is not built around a mandatory payment gateway: the free tier runs on the user's own key (BYOK) and a dedicated entitlement layer differentiates tiers without locking core function behind a checkout — extensible to any billing backend without redesign.

Ventute — consequences you can trust, because the machine, not the model, keeps the books.

Like this project

Completed work

Posted Jul 31, 2026

Deterministic AI simulation platform: high-concurrency Async Python (FastAPI) backend, event-sourced architecture, and native Rust (PyO3) compute kernel.

Likes

Views

Timeline

Jan 1, 2025 - Ongoing