docs: add backend setup guide and centralized API reference

README.md

@@ -13,27 +13,31 @@ faculties can adapt the platform to their own campuses.
 
 The solution comprises five collaborating layers:
 
-- **IoT layer** – ESP32-based sensor nodes send telemetry to a lightweight Flask
+- **IoT layer** - ESP32-based sensor nodes send telemetry to a lightweight Flask
   logger (`iot/logging`).
-- **Backend APIs** – A FastAPI service (`backend/app`) exposes CRUD endpoints for
+- **Backend APIs** - A FastAPI service (`backend/app`) exposes CRUD endpoints for
   projects, resources, locations, maintenance tickets, and sensor sites.
-- **GIS & Analytics** – Future modules will combine telemetry and asset data to
+- **GIS & Analytics** - Future modules will combine telemetry and asset data to
   power dashboards and risk assessments.
-- **Frontend** – Web dashboards and mobile apps consume the backend APIs.
-- **Deployment** – Infrastructure-as-code scripts will package the stack for on
+- **Frontend** - Web dashboards and mobile apps consume the backend APIs.
+- **Deployment** - Infrastructure-as-code scripts will package the stack for on
   campus or cloud hosting.
 
 Consult `docs/backend_crud_plan.md` for the architectural rationale that guided
 issue `#5` (CRUD API implementation).
 
 ### Module Overview
 
-- `iot/` – Firmware sketches and logging scripts for field sensors.
-- `backend/` – FastAPI application, domain models, services, and tests.
-- `docs/` – Supplemental guides and design notes.
+- `iot/` - Firmware sketches and logging scripts for field sensors.
+- `backend/` - FastAPI application, domain models, services, and tests.
+- `docs/` - Supplemental guides and design notes.
 - Additional directories (frontend, gis, deployment) will be filled as the
   broader initiative matures.
 
+Backend-specific onboarding now lives in [`backend/README.md`](backend/README.md)
+and the centralized endpoint reference is documented in
+[`docs/API_REFERENCE.md`](docs/API_REFERENCE.md).
+
 ## Backend Service (Issue #5 Deliverable)
 
 ### Prerequisites
@@ -122,8 +126,9 @@ institutional context.
 
 ## License
 
-MIT, Apache
+License is not yet specified. The README currently lists "MIT, Apache", which is ambiguous. Please add a LICENSE file to clarify the intended license.
 
 ## Maintainers
 
 Muwanga Erasto Kosea, Ouma Ronald
+

backend/.env.example

@@ -1,6 +1,14 @@
 # Default configuration for local development.
+
+# Async SQLAlchemy connection string used by the backend services.
 LIFELINE_DATABASE_URL=sqlite+aiosqlite:///./lifeline.db
+
+# Version string exposed in the FastAPI metadata and OpenAPI docs.
 LIFELINE_API_VERSION=0.1.0
+
+# Contact shown in the generated API documentation.
 LIFELINE_CONTACT_EMAIL=ict-support@lifeline.example.edu
+
+# Default and maximum page sizes for list endpoints.
 LIFELINE_PAGINATION_DEFAULT_LIMIT=20
 LIFELINE_PAGINATION_MAX_LIMIT=100

backend/README.md

@@ -0,0 +1,108 @@
+# LifeLine-ICT Backend Setup
+
+This guide focuses on the FastAPI backend located in `backend/`.
+
+## Prerequisites
+
+- Python 3.11+
+- `pip`
+- Optional: a virtual environment tool such as `venv`
+
+## Local Setup
+
+From the `backend/` directory:
+
+```bash
+python -m venv .venv
+```
+
+Activate the environment:
+
+```bash
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+# Linux or macOS
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Environment Variables
+
+Copy the sample configuration before running the app:
+
+```bash
+cp .env.example .env
+```
+
+If you are using PowerShell on Windows, the equivalent command is:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+### Key Settings
+
+- `LIFELINE_DATABASE_URL`: async database URL used by SQLAlchemy
+- `LIFELINE_API_VERSION`: version shown in the FastAPI docs
+- `LIFELINE_CONTACT_EMAIL`: support contact displayed in OpenAPI metadata
+- `LIFELINE_PAGINATION_DEFAULT_LIMIT`: default list size for collection endpoints
+- `LIFELINE_PAGINATION_MAX_LIMIT`: upper bound accepted by pagination params
+
+The default sample config uses local SQLite, which is enough for first-time
+setup and classroom development.
+
+## Database Migrations
+
+Run migrations from the `backend/` directory:
+
+```bash
+alembic upgrade head
+```
+
+Create a new migration when models change:
+
+```bash
+alembic revision --autogenerate -m "describe_change"
+```
+
+## Running the API
+
+If you are inside `backend/`, start the development server with:
+
+```bash
+uvicorn app.main:app --reload
+```
+
+Useful endpoints after startup:
+
+- Swagger UI: `http://127.0.0.1:8000/docs`
+- ReDoc: `http://127.0.0.1:8000/redoc`
+- App health: `http://127.0.0.1:8000/health`
+
+## Running Tests
+
+From the repository root:
+
+```bash
+pytest backend/tests
+```
+
+If you are already inside `backend/`, run:
+
+```bash
+pytest tests
+```
+
+## Optional Seed Data
+
+Populate sample data for demos or manual testing:
+
+```bash
+python scripts/seed_sample_data.py
+```