From 131283eae709e7fcb20e1efd28be7d63e068be3a Mon Sep 17 00:00:00 2001
From: samantha <me@samantha42.xyz>
Date: Sat, 21 Mar 2026 07:31:07 +0000
Subject: [PATCH] Add Configuration

---
 Configuration.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 Configuration.md

diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..eac2d6a
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,76 @@
+# Configuration
+ 
+The engine is configured entirely through environment variables. Copy `.env.example` to `.env` to get started.
+ 
+---
+ 
+## Environment Variables
+ 
+| Variable | Default | Description |
+|---|---|---|
+| `DB_PATH` | `fpa.db` | Path to the SQLite database file. Use `:memory:` to run entirely in-memory (useful for tests or ephemeral environments). |
+| `PORT` | `8080` | TCP port the HTTP server listens on. |
+ 
+---
+ 
+## .env.example
+ 
+```env
+DB_PATH=fpa.db
+PORT=8080
+```
+ 
+---
+ 
+## In-Memory Mode
+ 
+For tests or CI pipelines where you don't want a file left on disk:
+ 
+```env
+DB_PATH=:memory:
+```
+ 
+The schema is still applied via auto-migration on startup. Data is lost when the process exits.
+ 
+---
+ 
+## HTTP Server Timeouts
+ 
+Timeouts are hardcoded in `main.go` and are not currently configurable via environment variables:
+ 
+| Timeout | Value | Purpose |
+|---|---|---|
+| `ReadTimeout` | 10s | Maximum time to read the full request |
+| `WriteTimeout` | 30s | Maximum time to write the full response (set higher to allow for large variance reports) |
+| `IdleTimeout` | 120s | Maximum time to keep an idle keep-alive connection open |
+ 
+---
+ 
+## Logging
+ 
+The engine uses Go's `log/slog` with a JSON handler writing to stdout. All log entries are structured JSON, suitable for ingestion by log aggregators like Loki, Datadog, or CloudWatch.
+ 
+Example log lines:
+ 
+```json
+{"time":"2026-03-21T08:16:00Z","level":"INFO","msg":"server starting","port":"8080","db":"fpa.db"}
+{"time":"2026-03-21T08:16:05Z","level":"ERROR","msg":"migration failed","error":"..."}
+```
+ 
+Log level is not currently configurable — the logger runs at INFO.
+ 
+---
+ 
+## Deployment
+ 
+Because the engine compiles to a single binary with no runtime dependencies (SQLite is a pure-Go implementation), deployment is straightforward:
+ 
+```bash
+# Build
+go build -o fpa-engine ./main.go
+ 
+# Run
+DB_PATH=/data/fpa.db PORT=8080 ./fpa-engine
+```
+ 
+It can be containerised, run as a systemd service, or deployed to any platform that can run a Go binary. No Node, Python, or system SQLite library is required.
\ No newline at end of file