dangutdavid/nigeria-security-app

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.