Anthill

Anthill is a Rust and Svelte ERP-style application that currently runs as a unified backend binary (anthill-server) plus a SvelteKit frontend. Older documentation in this repository still refers to separately started backend services; that is no longer the default runtime model.

Current State

Stack

• Backend: Rust 1.82+, Axum, Tokio, SQLx, Utoipa
• Frontend: SvelteKit 2, Svelte 5, TypeScript, Tailwind CSS 4, shadcn-svelte
• AuthN/AuthZ: JWT cookies plus Casbin RBAC
• Database: PostgreSQL
• Cache and coordination: KeyDB
• Object storage: RustFS (S3-compatible)
• Gateway: APISIX
• Observability hooks: Prometheus endpoint in backend, optional tracing and monitoring compose files under infra/

Repository Layout

anthill/
├── server/                    # Unified anthill-server binary
├── services/                  # Domain modules and legacy service directories
│   ├── user_service/          # api/core/infra crates
│   ├── inventory_service/     # api/core/infra crates + legacy crate
│   ├── purchase_service/      # api/core/infra crates
│   ├── sales_service/         # api/core/infra crates
│   ├── accounting_service/    # api/core/infra crates
│   ├── manufacturing_service/ # api/core/infra crates
│   ├── enterprise_service/    # api crate
│   ├── order_service/         # legacy/prototype directory, not in workspace
│   ├── integration_service/   # legacy/prototype directory, not in workspace
│   └── payment_service/       # excluded from workspace
├── shared/                    # Shared Rust crates (auth, db, config, events, etc.)
├── frontend/                  # SvelteKit frontend
├── infra/                     # Docker, Podman, APISIX, Nginx, observability assets
├── migrations/                # SQLx migrations
├── tests/                     # E2E, load, and QA scripts
├── PROJECT_TRACKING/          # Delivery tracking and implementation notes
├── start-system.sh            # Recommended local startup script
└── stop-system.sh             # Matching local shutdown script

Quick Start

Prerequisites

• Rust toolchain 1.82+ with cargo
• Bun
• Docker or Podman
• sqlx-cli if you want the startup script to run migrations automatically

Recommended local run

From the project root:

./start-system.sh

What the script does:

• Detects Podman first, then Docker
• Starts PostgreSQL, KeyDB, RustFS, and APISIX
• Runs migrations when sqlx is installed, unless --skip-migrations is passed
• Starts anthill-server on port 8000
• Starts the frontend dev server on port 5173

Default local endpoints after startup:

• Frontend dev server: http://localhost:5173
• Backend health check: http://localhost:8000/health
• Backend OpenAPI UI: http://localhost:8000/docs
• APISIX gateway: http://localhost:9080
• RustFS API: http://localhost:9000
• RustFS console: http://localhost:9001

Stop everything with:

./stop-system.sh

Useful startup flags

./start-system.sh --docker
./start-system.sh --podman
./start-system.sh --containers-only
./start-system.sh --skip-migrations

Manual Local Setup

Use this path when you want to debug specific pieces instead of relying on start-system.sh.

1. Start infrastructure

With Docker:

docker compose -f infra/docker_compose/docker-compose.yml up -d

With Podman:

cd infra/podman
cp .env.example .env
podman compose -f docker-compose.podman.yml up -d
cd ../..

2. Export local development environment

start-system.sh uses these defaults for local development. If you run services manually, export them yourself:

export DATABASE_URL=postgres://user:password@localhost:5432/inventory_db
export REDIS_URL=redis://localhost:6379
export JWT_SECRET=anthill-dev-secret-key-change-in-production
export RUSTFS_ENDPOINT=http://localhost:9000
export RUSTFS_ACCESS_KEY=rustfsadmin
export RUSTFS_SECRET_KEY=rustfsadmin
export CORS_ORIGINS=http://localhost:5173,http://localhost:9080
export SQLX_OFFLINE=true

3. Run migrations

cargo install sqlx-cli --no-default-features --features postgres
sqlx migrate run

4. Start the unified backend

cargo run --bin anthill-server

5. Start the frontend

cd frontend
bun install
bun run dev

6. Optional frontend environment

frontend/.env.example defaults PUBLIC_API_GATEWAY_URL to http://localhost:8000, which is convenient for direct local development. If you want the browser to go through APISIX locally, point it to http://localhost:9080 instead.

Development Commands

Backend workspace

cargo fmt --all
SQLX_OFFLINE=true cargo check --workspace
SQLX_OFFLINE=true cargo clippy --workspace -- -D warnings
cargo test --workspace

Notes:

• cargo test --workspace includes crates that may expect a database or other local services to be available.
• The active backend entrypoint is anthill-server; do not assume older per-service cargo run --bin ... commands are still valid.

Frontend

cd frontend
bun install
bun run check
bun run lint
bun run test:unit
bun run test:e2e
bun run test
bun run build

Separate E2E suite under tests/e2e

There is also a standalone Playwright suite under tests/e2e/.

cd tests/e2e
npm install
npm test

Integration-test containers

For isolated PostgreSQL and KeyDB instances used by some tests:

docker compose -f docker-compose.test.yml up -d

SQLx Policy

The repository standard is SQLx compile-time checked macros plus committed offline metadata.

Rules:

• Prefer sqlx::query!, sqlx::query_as!, and sqlx::query_scalar! for static SQL
• Treat .sqlx/ as required workspace metadata
• When migrations or query macros change, regenerate metadata and commit the result

Update metadata with:

cargo install sqlx-cli --no-default-features --features postgres
cargo sqlx prepare

CI or local verification:

cargo sqlx prepare --check

Infra Notes

• Docker compose files live under infra/docker_compose/
• Podman equivalents live under infra/podman/
• APISIX is configured in standalone mode via infra/apisix/
• Optional tracing and monitoring compose files are already checked in under infra/docker_compose/ and infra/podman/
• Nginx assets under infra/nginx/ are not the main local development path; local development is centered on APISIX plus the dev frontend

Where To Look Next

• ARCHITECTURE.md for system design notes
• STRUCTURE.md for codebase conventions and layout
• frontend/README.md for frontend-specific details
• infra/podman/README.md for Podman workflow notes
• PROJECT_TRACKING/TASKS_OVERVIEW.md for implementation tracking

Contributing Notes

• Expect mixed maturity across modules; this repository is still in active implementation
• Prefer updating documentation near the code when behavior changes
• If you touch migrations or SQLx query macros, update .sqlx/ in the same change
• If you update startup behavior, keep README.md, start-system.sh, and infra compose files aligned