diff --git a/README.md b/README.md index b0217c3..2ea672c 100644 --- a/README.md +++ b/README.md @@ -1,129 +1,82 @@ -# LifeLine-ICT - -## Project Summary - -LifeLine-ICT is a digital infrastructure management platform that supports the -Uganda University ICT department. The system tracks strategic ICT projects, -inventory assets, IoT deployments, and the maintenance activities that keep -digital services reliable for students and researchers. The repository contains -code for the IoT device layer, the backend APIs, and supporting documentation so -faculties can adapt the platform to their own campuses. - -### High-Level Architecture +LifeLine-ICT +Project Summary +LifeLine-ICT is a digital infrastructure management platform that supports the Uganda University ICT department. The system tracks strategic ICT projects, inventory assets, IoT deployments, and the maintenance activities that keep digital services reliable for students and researchers. The repository contains code for the IoT device layer, the backend APIs, and supporting documentation so faculties can adapt the platform to their own campuses. +High-Level Architecture The solution comprises five collaborating layers: -- **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 - projects, resources, locations, maintenance tickets, and sensor sites. -- **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 - campus or cloud hosting. - -Consult `docs/backend_crud_plan.md` for the architectural rationale that guided -issue `#5` (CRUD API implementation). - -### Module Overview +IoT Layer: ESP32-based sensor nodes send telemetry to a lightweight Flask logger (iot/logging). -- `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 APIs: A FastAPI service (backend/app) exposes CRUD endpoints for projects, resources, locations, maintenance tickets, and sensor sites. -## Backend Service (Issue #5 Deliverable) +GIS & Analytics: Future modules will combine telemetry and asset data to power dashboards and risk assessments. -### Prerequisites +Frontend: Web dashboards and mobile apps consume the backend APIs. -- Python 3.11+ -- `pip` or `uv` for dependency management -- Optional: `uvicorn` CLI for local development +Deployment: Infrastructure-as-code scripts will package the stack for on-campus or cloud hosting. -### Installation +Consult docs/backend_crud_plan.md for the architectural rationale that guided Issue #5 (CRUD API implementation). -```bash -python -m venv .venv -source .venv/bin/activate -pip install -r backend/requirements.txt -``` +Module Overview +iot/: Firmware sketches and logging scripts for field sensors. -### Running the API +backend/: FastAPI application, domain models, services, and tests. -```bash -uvicorn backend.app.main:app --reload -``` +docs/: Supplemental guides and design notes. -The service listens on `http://127.0.0.1:8000` by default. OpenAPI -documentation is available at `http://127.0.0.1:8000/docs`. +Additional Directories: Frontend, GIS, and Deployment directories will be populated as the broader initiative matures. -### Core Endpoints +Backend Service +Prerequisites +Python 3.11+ -| Entity | Base Path | Notes | -| --- | --- | --- | -| Projects | `/api/v1/projects` | CRUD with pagination & search | -| ICT Resources | `/api/v1/resources` | Validates project/location references and enforces ticket rules | -| Locations | `/api/v1/locations` | CRUD with geo metadata | -| Maintenance Tickets | `/api/v1/maintenance-tickets` | Requires resolution metadata when closing a ticket | -| Sensor Sites | `/api/v1/sensor-sites` | Links IoT deployments to resources, projects, and locations | +pip or uv for dependency management -Each list endpoint accepts `limit`, `offset`, and `search` query parameters and -returns pagination metadata to keep API consumers informed. +Optional: uvicorn CLI for local development -### Running Tests +Installation +Running the API +The service listens on http://127.0.0.1:8000 by default. OpenAPI documentation is available at http://127.0.0.1:8000/docs. -```bash -pytest backend/tests -``` +Core Endpoints +Each list endpoint accepts limit, offset, and search query parameters and returns pagination metadata to keep API consumers informed. -The suite provisions an in-memory SQLite database and covers both service-level -rules (such as blocking resource deletion while tickets remain open) and API -contracts. +Running Tests +The suite provisions an in-memory SQLite database and covers both service-level rules (such as blocking resource deletion while tickets remain open) and API contracts. -### Database Migrations - -This project uses [Alembic](https://alembic.sqlalchemy.org/en/latest/) for database migrations. +Database Migrations +This project uses for database migrations. To create a new migration, run: -```bash -alembic revision --autogenerate -m "" -``` - To apply migrations to the database, run: -```bash -alembic upgrade head -``` +Data Model Highlights +The backend models capture the following relationships: -### Data Model Highlights +Projects aggregate ICT resources and sensor sites. -The backend models capture the following relationships: +Resources optionally link to projects and locations, and can host sensor deployments. + +Maintenance tickets belong to resources and require closure notes when marked resolved. -- Projects aggregate ICT resources and sensor sites. -- Resources optionally link to projects and locations, and can host sensor - deployments. -- Maintenance tickets belong to resources and require closure notes when marked - resolved. +Consult the service-layer docstrings for detailed business rules and institutional context. -Consult the service-layer docstrings for detailed business rules and -institutional context. +Contributing +Create an issue or pick an existing one (see issues.md). -## Contributing +Branch from main: git checkout -b feature/your-feature. -1. Create an issue or pick an existing one (see `issues.md`). -2. Branch from `main`: `git checkout -b feature/your-feature`. -3. Follow the layered structure (`api`, `services`, `repositories`, `models`) to - keep contributions organised. -4. Write tests and run `pytest backend/tests` before opening a pull request. -5. Document behaviour changes in code docstrings or the project docs. +Follow the layered structure (api, services, repositories, models) to keep contributions organized. -## License +Write tests and run pytest backend/tests before opening a pull request. -MIT, Apache +Document behavior changes in code docstrings or the project docs. -## Maintainers +License +Licensed under MIT and Apache. +git add . +Maintainers +Muwanga Erasto Kosea -Muwanga Erasto Kosea, Ouma Ronald +Ouma Ronald \ No newline at end of file