Getting Started

Prerequisites

Go 1.22 or later (the router uses method+path patterns introduced in 1.22)
No other external dependencies — SQLite is bundled via modernc.org/sqlite (pure Go, no CGO required)

Installation

git clone https://git.samantha42.xyz/samantha/FPandA-Engine
cd FPandA-Engine

Copy the example environment file:

cp .env.example .env

Install Go module dependencies:

go mod tidy

Running the Server

go run ./main.go

On first run, the engine will:

Open (or create) the SQLite database at the path specified by DB_PATH (defaults to fpa.db in the current directory)
Run CREATE TABLE IF NOT EXISTS migrations automatically — no migration tool needed
Start the HTTP server on port 8080 (or the value of PORT)

You should see structured JSON log output:

{"time":"...","level":"INFO","msg":"server starting","port":"8080","db":"fpa.db"}

Verify It's Running

curl http://localhost:8080/api/v1/health
# → {"status":"ok"}

Load Demo Data

The repo includes a seed script with realistic data for Engineering, Sales, and Marketing departments across FY2024 period 9. See scripts/seed_demo.sh or POST directly to /api/v1/actuals/ingest.

Stopping the Server

Send SIGINT or SIGTERM (i.e. Ctrl+C). The server performs a graceful shutdown with a 15-second drain timeout before closing.

Running Tests

go test ./...

Tests use Go's built-in testing package. The database is configured to use :memory: for tests so no disk state is left behind.

Next Steps

See API Reference for all available endpoints
See Finance Concepts to understand favourability logic and budget versioning
See Configuration for all available environment variables