SAPOT — Documentation Index
Browse this documentation as a website by running pnpm start inside docs/site/.
SAPOT (Search and Patrol Operations Technology) is a LAN-first disaster-response communications platform. It provides messaging, voice/video calls, GPS tracking, and announcements over a local-area network (LAN) when internet connectivity is unavailable. All core functions — messaging, peer discovery, and calls — operate without an internet connection. The server coordinates authentication, sync, and signalling but does not relay chat messages.
Components
| Name | Role | Primary Stack | Local Docs |
|---|
mobile-app/sapot-mobile-app/ | Android app — messaging, voice/video calls, GPS sharing, announcements, peer discovery | Expo, React Native, TypeScript, WatermelonDB, WebRTC | Mobile App Docs |
server/ | Backend — auth, sync, signalling relay, GPS, admin, GSM proxy, MikroTik telemetry | FastAPI, Python, MariaDB, Redis, Gunicorn | — |
admin-frontend/sapot-admin/ | Admin/rescuer dashboard — user management, GPS map, network analytics | Next.js App Router, TypeScript | — |
GSM-module/ | SMS gateway — sends SMS when LAN messaging fails | FastAPI, pyserial, Arduino/AT commands | — |
captive-portal/ | MikroTik hotspot login pages shown to users joining the network | Static HTML/CSS/JS | — |
tileserver/ | Offline map tile server for the GPS map | — | — |
deploy/ | Offline, immutable Docker deployment bundle tooling | Bash, Docker Compose | deployment/docker-bundle.md |
By Role
Documentation Index
Architecture
| Document | Contents |
|---|
| architecture/system-overview.md | Component responsibilities, system boundaries, communication matrix, roles |
| architecture/assumptions-and-constraints.md | Consolidated deployment assumptions and technical constraints, with links to the ADRs/threat model they come from |
| architecture/component-map.md | Process/service topology, ports, deployment units, what talks to what |
| architecture/data-flow.md | Sync flow, message delivery (WS relay, LAN P2P, SMS fallback), call signalling, GPS streaming — with Mermaid diagrams |
| architecture/networking-lan-model.md | LAN topology, MikroTik router role, mDNS discovery, client isolation considerations |
| architecture/security-architecture.md | Auth, password hashing, E2E encryption key hierarchy and flows, rate limiting, LAN transport security |
| architecture/threat-model.md | Trust boundaries, in-scope attack surfaces, device theft / router compromise / insider threat scenarios, known risks |
| adr/ | Architecture Decision Records — NaCl box, WatermelonDB, P2P calls, LAN-first design, roles model, Alembic server migrations |
Mobile App (Detailed)
These live inside the mobile app sub-project at mobile-app/sapot-mobile-app/docs/:
| Document | Contents |
|---|
| ONBOARDING.md | Developer onboarding — where complexity lives and how to navigate the codebase |
| ARCHITECTURE.md | Service map, DI containers, transport modes, encryption, adapters |
| SYNC.md | Pull/push sync cycle, trigger points, entity list, field normalization |
| API.md | REST endpoint reference |
| DATABASE.md | WatermelonDB schema and migrations |
| CALL_FLOW.md | Call lifecycle and message types |
| LAN_MESSENGER.md | LAN-only messaging behaviour and constraints |
| CONNECTION_MESSAGES.md | WebSocket, TCP, and WebRTC data-channel message catalogue |
| ENV_CONFIG.md | Environment variables, build variants, secure-storage keys |
| TESTING.md | Test utilities, mock patterns, conventions |
| STATE_MANAGEMENT.md | The app's seven state mechanisms, sources of truth, debugging pain points |
| system-boundaries.md | UI/hooks/service layer boundaries |
| design-system.md | Material Design 3 theming via react-native-paper |
| conventions.md | Code style and TypeScript conventions |
| READABILITY_AUDIT.md | Codebase readability/maintainability audit |
| adr/ | Mobile-specific Architecture Decision Records (WebRTC reconnect/rebuild behaviour) |
| diagrams/ | Mermaid sequence diagrams for startup, LAN messaging, calls, GPS, SMS, guest user, security, encryption |
| audits/ | QA test cases, regression suite, automation plan |
CI/CD
| Document | Contents |
|---|
.github/workflows/EXPO_ANDROID_CI_DOCUMENTATION.md | Expo Android CI/CD workflow |
Getting Started
API
| Document | Contents |
|---|
| api/README.md | How to discover the live API base URL and spec (/docs, /redoc, /openapi.json) |
| api/conventions.md | Shared API conventions (auth, errors, rate limits) |
api/openapi/ | Committed OpenAPI YAML fragments per feature, generated from the live server |
Database
Deployment
| Document | Contents |
|---|
| deployment/overview.md | Deployment topology and component overview |
| deployment/server.md | FastAPI server deployment |
| deployment/environment-config.md | Environment variables for every component |
| deployment/secrets-management.md | Secret storage and rotation |
| deployment/monitoring-logging.md | Monitoring and logging setup |
| deployment/runbooks.md | Backup/restore, manual DB DDL application, TLS rotation, rollback, disaster recovery |
| deployment/incident-response.md | Severity levels, roles, and communication process during a live incident |
| deployment/maintenance.md | Recurring backup/cert/log/dependency upkeep schedule |
| deployment/mobile-eas.md | Mobile app EAS build/deploy |
| deployment/admin-frontend.md | Admin dashboard deployment |
| deployment/gsm-module.md | GSM module deployment |
| deployment/tileserver.md | Offline tileserver deployment |
| deployment/docker-bundle.md | Offline Docker bundle build, install, upgrade, and recovery |
| deployment/install-ubuntu-server.md | First-install walkthrough: CA USB stick, Docker Engine on Ubuntu Server 24.04, build, transfer, install, verify |
Features
Per-feature design/requirements/testing docs live under features/<name>/, each with a README.md summary: account-recovery, admin-management, authentication, calls, e2e-encryption, gps, messaging, sms-gateway, sync.
Troubleshooting
See TROUBLESHOOTING.md for common setup and connectivity failures across all components.
Glossary
See GLOSSARY.md for definitions of SAPOT-specific terms (roles, LAN, signalling, sync, etc.).
Root-Level Documents
| Document | Contents |
|---|
README.md | Repository overview, architecture, and quick-start links |
CONTRIBUTING.md | Branching, commit conventions, and PR workflow |
SECURITY.md | Vulnerability disclosure process and known security posture |
LICENSE | MIT license |
VERSIONING.md | Git-tag-driven versioning and release process (mobile, server, admin, captive portal, GSM module — independent) |
CHANGELOG.md | Notable changes per release |
Known Gap
Physical deployment steps — MikroTik router configuration for a real site, APK distribution to rescuer devices, onboarding rescuers at an incident site — are not yet documented. See devops/README.md and qa/README.md for what is covered for those workflows.