From 0bc800a971ad1470aa65939255d5b055f7b7d55a Mon Sep 17 00:00:00 2001
From: Joao Carreira <jfmcarreira@gmail.com>
Date: Tue, 6 Oct 2026 22:37:20 +0100
Subject: [PATCH] feat: add local enviroment

---
 AGENTS.md            |  8 ++++++++
 Makefile             | 16 ++++++++++++----
 README.md            | 28 ++++++++++++++++++++++++++++
 docs/ARCHITECTURE.md |  2 ++
 4 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index aa7542f..8db2cbf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,14 @@ live in `requirements-dev.txt`.
 Read `docs/DOMAIN.md` for business rules and `docs/ARCHITECTURE.md` for lifecycle
 and deployment details. See `README.md` for the test workflow.
 
+## Local development
+
+Run `make dev` to create/reuse `.venv`, install development dependencies, create
+`data/`, and start Uvicorn with auto-reload on `127.0.0.1:8000`. Use
+`make dev PORT=8001` to change the port. Application settings come from the
+environment and optional `.env`; database migrations and initial seeding run on
+startup. No separate setup command is needed.
+
 ## Development conventions
 
 - Follow existing typed Python, snake_case names, and SQLAlchemy 2 mapped models.
diff --git a/Makefile b/Makefile
index 2027968..5f7a235 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,15 @@
-.PHONY: test
+.PHONY: test dev _install
 
-test:
-	@test -x .venv/bin/python || python3 -m venv .venv
-	@.venv/bin/python -m pip install --quiet -r requirements-dev.txt
+PORT ?= 8000
+
+test: _install
 	@.venv/bin/python -m pytest $(ARGS); status=$$?; \
 		if [ $$status -eq 5 ]; then exit 0; else exit $$status; fi
+
+dev: _install
+	@mkdir -p data
+	@.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port "$(PORT)" --reload --reload-dir app
+
+_install:
+	@test -x .venv/bin/python || python3 -m venv .venv
+	@.venv/bin/python -m pip install --quiet -r requirements-dev.txt
diff --git a/README.md b/README.md
index b63c49e..3967b16 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,34 @@ A shift rota application built with FastAPI, SQLite/SQLAlchemy, and server-rende
 Jinja templates. It manages night and lunch schedules, teams, shared user logins,
 shift swaps, calendar subscriptions, and optional email notifications.
 
+## Run locally
+
+With Python 3.12+ (including `venv`/pip) and `make` installed, run:
+
+```sh
+make dev
+```
+
+This creates/reuses `.venv`, installs development dependencies, creates `data/`,
+and starts Uvicorn with auto-reload at <http://localhost:8000>. Startup applies
+migrations and seeds the initial administrator and schedules. Stop it with **Ctrl+C**.
+No virtualenv activation, Docker, or separate database setup is needed.
+
+The app reads `.env` if present; otherwise it uses its development defaults,
+including `data/bar_rota.db` and the initial login `admin` / `change-me-now`.
+Use a local SQLite path in `DATABASE_URL` and `SESSION_HTTPS_ONLY=false` for local
+HTTP development. Settings such as `INITIAL_ADMIN_USERNAME` and
+`INITIAL_ADMIN_PASSWORD` override the defaults when the database is first seeded.
+
+To use another port:
+
+```sh
+make dev PORT=8001
+```
+
+Update `BASE_URL` to match if using email notification links. The Makefile port
+defaults to `8000`; override it on the command line or through an exported `PORT`.
+
 ## Run with Docker Compose
 
 `compose.yaml` is a minimal deployment example. With Docker and Docker Compose
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 37a15d1..2746e2d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -4,6 +4,8 @@
 
 Single FastAPI process with server-rendered HTML and a SQLite database volume. This keeps deployment suitable for a small VPS, NAS or home server.
 
+For local development, `make dev` prepares the host virtualenv and default `data/` directory, then runs Uvicorn on `127.0.0.1:8000` with auto-reload for `app/`. Override the port with `make dev PORT=8001`. The app uses environment/`.env` settings and performs migrations and initial seeding during startup, just as it does in production.
+
 ## Layers
 
 - `models.py`: persistence schema.