# dangutdavid/nigeria-security-app architecture

> Architecture diagram of the GitHub repository dangutdavid/nigeria-security-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dangutdavid/nigeria-security-app
- Repository: https://github.com/dangutdavid/nigeria-security-app

## Overview

1. This is a pnpm monorepo built around a mobile-first public-safety platform for Nigerian agencies. The main production pieces are the Expo React Native app in `artifacts/mobile`, the Express API in `artifacts/api-server`, and shared contract/schema packages under `lib/`.

2. The mobile app is the primary user-facing system. It is organized by Expo Router route groups that map to roles and workspaces: citizen/public flows, FRSC, Police, VIO, Civil Defence, and Admin. That structure is important for the architecture diagram because navigation is role-scoped rather than a single generic app shell.

3. The mobile app supports both open citizen flows and authenticated agency/admin flows. Public users can submit and track incidents, report theft, view alerts, and use the assistant. Agency users sign in with badge/PIN, while admins get cross-agency oversight, agency management, user management, referrals, audit views, and reassignment tools.

4. Mobile state is mostly local-first today. The app uses context providers and repository/service layers to isolate features such as auth, agencies, incidents, crime reports, theft reports, inspections, patrol, referrals, and notifications. Many of these services read/write through AsyncStorage-backed flows, with a feature flag path for API-first calls.

5. The mobile app also has platform services for maps, permissions, notifications, and token handling. Map views have native and fallback variants, the notification layer includes in-app center plus push readiness, and some components are built specifically to handle offline-safe or coordinate-safe rendering.

6. The API server in `artifacts/api-server` is an Express app mounted under `/api`. Its current route surface includes health checks, auth, citizen reports, reports, notifications, assistant support, and an MVP route set. The key architectural boundary is that all backend access is organized behind route modules and an auth middleware layer.

7. Server-side persistence is currently mixed: there are in-memory fallback stores for reports, notifications, and related data, while PostgreSQL/Drizzle support is partially wired as the production direction. That means the server is already shaped as the authoritative backend, even though some flows still fall back to mock storage.

8. Authentication and authorization are a major boundary. The mobile app holds the client-side session/token handling, while the API server enforces scoped access through middleware. The repo’s README emphasizes agency ownership boundaries, admin-wide visibility, and auditability, so the architecture should show authorization as a first-class cross-cutting concern.

9. Shared contracts are split into three library layers. `lib/api-spec` contains the OpenAPI contract, `lib/api-zod` contains shared validation schemas and types, and `lib/api-client-react` contains a generated React client. These packages form the contract boundary between mobile and server and are the mechanism for keeping the API shape consistent.

10. `lib/db` holds the Drizzle/PostgreSQL schema and config. It is the data-model layer intended to back the server once the remaining persistence work is completed, so it sits below the API server rather than being consumed directly by mobile.

11. The `artifacts/mockup-sandbox` project is separate from the product architecture. It is a standalone UI/mockup environment with Vite and component primitives, useful for previewing screens but not part of the mobile/server runtime path.

12. Tooling reflects a TypeScript-first workspace with separate build and typecheck flows per package. The repo expects Node 22+, uses pnpm workspace filters, and treats mobile, server, and shared libraries as independently buildable units. For an architecture diagram, the clearest top-level view is: mobile clients and admin/agency workspaces on one side, Express API and persistence on the other, with shared contract libraries bridging the two.

Main entry points: [`artifacts/api-server/src/routes/index.ts`](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/routes/index.ts) (Route modules), [`artifacts/mobile/app/_layout.tsx`](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/_layout.tsx) (App shell), [`artifacts/mobile/services/authRepository.ts`](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/services/authRepository.ts) (Repositories), [`artifacts/mobile/app/report-incident.tsx`](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/report-incident.tsx) (Public flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_mobile_shell["App shell<br/>expo-router entry<br/>[_layout.tsx]"]
  node_mobile_public["Public flows<br/>citizen routes"]
  node_mobile_admin["Admin workspace<br/>admin routes<br/>[index.tsx]"]
  node_mobile_police["Police workspace<br/>police routes<br/>[index.tsx]"]
  node_mobile_vio["VIO workspace<br/>vio routes<br/>[index.tsx]"]
  node_mobile_civil_defence["Civil Defence<br/>civil-defence routes<br/>[index.tsx]"]
  node_mobile_context(("State providers<br/>context layer<br/>[AuthContext.tsx]"))
  node_mobile_services["Repositories<br/>service layer<br/>[authRepository.ts]"]
  node_mobile_platform["Platform services<br/>device services"]
end

subgraph group_api["API server"]
  node_api_app["Express app<br/>api server<br/>[app.ts]"]
  node_api_routes["Route modules<br/>route boundary<br/>[index.ts]"]
  node_api_auth{{"Auth middleware<br/>authorization<br/>[authMiddleware.ts]"}}
  node_api_stores[("Fallback stores<br/>persistence")]
end

subgraph group_shared["Shared libs"]
  node_api_db[("DB schema<br/>drizzle schema<br/>[index.ts]")]
  node_api_spec["OpenAPI spec<br/>contract<br/>[openapi.yaml]"]
  node_api_zod["Shared zod<br/>validation schemas<br/>[index.ts]"]
  node_api_client["React client<br/>generated client<br/>[index.ts]"]
end

subgraph group_sandbox["Sandbox"]
  node_mockup["Mockup sandbox<br/>ui preview<br/>[App.tsx]"]
end

subgraph group_tooling["Tooling"]
end

node_mobile_shell -->|"routes to"| node_mobile_public
node_mobile_shell -->|"routes to"| node_mobile_admin
node_mobile_shell -->|"routes to"| node_mobile_police
node_mobile_shell -->|"routes to"| node_mobile_vio
node_mobile_shell -->|"routes to"| node_mobile_civil_defence
node_mobile_shell -->|"wraps"| node_mobile_context
node_mobile_context -->|"uses"| node_mobile_services
node_mobile_services -->|"uses"| node_mobile_platform
node_mobile_services -->|"calls"| node_api_client
node_api_client -->|"generated from"| node_api_spec
node_api_zod -->|"derived from"| node_api_spec
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"guards"| node_api_auth
node_api_routes -->|"reads/writes"| node_api_stores
node_api_routes -->|"targets"| node_api_db
node_api_stores -.->|"evolves toward"| node_api_db
node_mobile_services -->|"consumes"| node_api_routes
node_mobile_admin -->|"oversight"| node_api_routes
node_mobile_public -->|"submits"| node_api_routes
node_mobile_platform -->|"push/readiness"| node_api_routes
node_mockup -.->|"informs"| node_mobile_shell

click node_mobile_shell "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/_layout.tsx"
click node_mobile_public "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/report-incident.tsx"
click node_mobile_admin "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(admin)/index.tsx"
click node_mobile_police "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(police)/index.tsx"
click node_mobile_vio "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(vio)/index.tsx"
click node_mobile_civil_defence "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(civil-defence)/index.tsx"
click node_mobile_context "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/context/AuthContext.tsx"
click node_mobile_services "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/services/authRepository.ts"
click node_mobile_platform "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/services/pushNotificationService.ts"
click node_api_app "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/app.ts"
click node_api_routes "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/routes/index.ts"
click node_api_auth "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/middlewares/authMiddleware.ts"
click node_api_stores "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/lib/citizenReportStore.ts"
click node_api_db "https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/db/src/schema/index.ts"
click node_api_spec "https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-spec/openapi.yaml"
click node_api_zod "https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-zod/src/index.ts"
click node_api_client "https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-client-react/src/index.ts"
click node_mockup "https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mockup-sandbox/src/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mobile_shell,node_mobile_public,node_mobile_admin,node_mobile_police,node_mobile_vio,node_mobile_civil_defence,node_mobile_context,node_mobile_services,node_mobile_platform toneBlue
class node_api_app,node_api_routes,node_api_auth,node_api_stores toneAmber
class node_api_db,node_api_spec,node_api_zod,node_api_client toneMint
class node_mockup toneRose
```

## Components

### Mobile app

Expo React Native client and its role-scoped workspaces

- [App shell](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/_layout.tsx): expo-router entry · Top-level Expo Router layout and cross-app navigation shell · `artifacts/mobile/app/_layout.tsx`
- [Public flows](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/report-incident.tsx): citizen routes · Open citizen-facing incident, theft, alert, assistant, and tracking screens · `artifacts/mobile/app/report-incident.tsx`
- [Admin workspace](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(admin)/index.tsx): admin routes · Cross-agency oversight, users, agencies, audit, referrals, and reassignment views · `artifacts/mobile/app/(admin)/index.tsx`
- [Police workspace](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(police)/index.tsx): police routes · Police role-scoped workspace for crime reports, vehicle checks, alerts, and map views · `artifacts/mobile/app/(police)/index.tsx`
- [VIO workspace](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(vio)/index.tsx): vio routes · Vehicle inspection officer workspace with inspections and certificates · `artifacts/mobile/app/(vio)/index.tsx`
- [Civil Defence](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/app/(civil-defence)/index.tsx): civil-defence routes · Civil Defence role-scoped alerts, incidents, and map workspace · `artifacts/mobile/app/(civil-defence)/index.tsx`
- [State providers](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/context/AuthContext.tsx): context layer · Auth, agencies, incidents, crime reports, theft reports, inspections, patrol, referrals, and theme state · `artifacts/mobile/context/AuthContext.tsx`
- [Repositories](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/services/authRepository.ts): service layer · Local-first service and repository adapters with API-first feature paths · `artifacts/mobile/services/authRepository.ts`
- [Platform services](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mobile/services/pushNotificationService.ts): device services · Maps, permissions, notifications, token handling, and offline-safe render helpers · `artifacts/mobile/services/pushNotificationService.ts`

### API server

Express backend and request boundary

- [Express app](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/app.ts): api server · Backend application mounted under /api · `artifacts/api-server/src/app.ts`
- [Route modules](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/routes/index.ts): route boundary · Health, auth, citizen reports, reports, notifications, assistant, and MVP routes · `artifacts/api-server/src/routes/index.ts`
- [Auth middleware](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/middlewares/authMiddleware.ts): authorization · Scoped access enforcement layer for backend requests · `artifacts/api-server/src/middlewares/authMiddleware.ts`
- [Fallback stores](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/api-server/src/lib/citizenReportStore.ts): persistence · In-memory report, notification, and support stores used where production persistence is incomplete · `artifacts/api-server/src/lib/citizenReportStore.ts`

### Shared libs

Contracts, generated clients, and database schema packages

- [DB schema](https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/db/src/schema/index.ts): drizzle schema · PostgreSQL/Drizzle data model intended as the production persistence layer · `lib/db/src/schema/index.ts`
- [OpenAPI spec](https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-spec/openapi.yaml): contract · Authoritative API contract definition shared across client and server · `lib/api-spec/openapi.yaml`
- [Shared zod](https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-zod/src/index.ts): validation schemas · Shared validation schemas and types generated from the API contract · `lib/api-zod/src/index.ts`
- [React client](https://github.com/dangutdavid/nigeria-security-app/blob/main/lib/api-client-react/src/index.ts): generated client · Generated client for consuming the shared API contract from React-based apps · `lib/api-client-react/src/index.ts`

### Sandbox

Standalone mockup and preview environment

- [Mockup sandbox](https://github.com/dangutdavid/nigeria-security-app/blob/main/artifacts/mockup-sandbox/src/App.tsx): ui preview · Standalone Vite-based mockup and screen preview environment · `artifacts/mockup-sandbox/src/App.tsx`

## Connections

- App shell → Public flows: routes to · App shell exposes public citizen flows
- App shell → Admin workspace: routes to · Role-scoped admin workspace
- App shell → Police workspace: routes to · Police workspace routing
- App shell → VIO workspace: routes to · VIO workspace routing
- App shell → Civil Defence: routes to · Civil Defence workspace routing
- App shell → State providers: wraps · Global providers supply state and session context
- State providers → Repositories: uses · Feature contexts delegate persistence and sync to repositories
- Repositories → Platform services: uses · Repositories depend on platform capabilities such as notifications and maps
- Repositories → React client: calls · API-first paths use the generated client
- React client → OpenAPI spec: generated from · React client is derived from the shared contract
- Shared zod → OpenAPI spec: derived from · Validation types follow the same API contract
- Express app → Route modules: mounts · Express app composes route modules under /api
- Route modules → Auth middleware: guards · Protected routes pass through auth middleware
- Route modules → Fallback stores: reads/writes · Current backend persistence includes in-memory fallback stores
- Route modules → DB schema: targets · Production persistence direction is PostgreSQL via Drizzle
- Fallback stores → DB schema: evolves toward · Fallback stores mirror the eventual database-backed model
- Repositories → Route modules: consumes · Mobile repositories call the backend route surface when online
- Admin workspace → Route modules: oversight · Admin screens rely on cross-agency backend data
- Public flows → Route modules: submits · Citizen incident, theft, and tracking flows interact with backend APIs
- Platform services → Route modules: push/readiness · Notification and assistant platform features depend on backend support
- Mockup sandbox → App shell: informs · Sandbox previews product screens but is not part of runtime path