Technical Flows · Architecture · Sprint Worksheets · Task Assignments · Platform Documentation
OAuth 2.0 · JWT (15m) · Refresh (7d) · Mobile biometrics
POST /auth/refresh → rotate both tokens → retry original request
Force re-auth → full OAuth handshake → new token pair
JWT claims extraction · role check · route policy enforcement
Log attempt → audit_log table → rate-limit alert if 5+ fails in 10m
Upload → S3 → SQS/BullMQ → Worker → PostgreSQL batch insert
Multer middleware → validate file type (csv/xlsx) → stream to S3 multipart → return 202 Accepted
SQS.sendMessage({ s3Key, auditSessionId, uploadedBy }) — or BullMQ.add('ingest', payload)
S3.getObject() → createReadStream() → csv-parser/exceljs → sanitize rows → validate batchId format → normalize dates to ISO 8601
pg COPY protocol for 50K+ rows → link to audit_session_id → raw lines in JSONB column → status = READY
WatermelonDB pull → offline scan → UUID v4 idempotency → pending_sync queue
GET /sync/pull?last_pulled_at={ts} → Sync Engine returns delta → WatermelonDB.database.sync()
react-native-camera / Bluetooth HID → lookup localDB.get('items', barcode) → display item → prompt qty
Same barcode scanned? → scan_records.update(r => r.qty += newQty) — never overwrite. Prevents data loss.
scan_records.create({ id: uuidv4(), barcode, qty, zone_id, session_id, status: 'pending_sync', ts })
NetInfo.addEventListener → POST /sync/push { changes: [...] } — exponential backoff (1s→2s→4s→8s)
Additive merge · UUID dedup · Δ = expected − physical
status='verified'
Flag by threshold tier
Possible HIS error
expiry_date < NOW()
Aggregate → financial calc → dashboard → CSV export → HIS feedback
4-tier: Edge → Gateway → App → Data
Defense-in-depth · append-only ledger · KMS encryption
Nginx enforces HTTPS only · brute-force detection
Short JWT · rotating refresh · middleware on every route
EBS/RDS encrypted · mobile Keychain/Keystore · S3 SSE
No UPDATE/DELETE on scan_records · soft-delete + version column · full history
Key REST endpoints for the PharmaAudit platform
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| POST | /auth/login | OAuth login initiation | Public |
| POST | /auth/refresh | Rotate JWT + refresh token | Cookie |
| POST | /api/audit | Create audit session | Admin |
| POST | /api/audit/{id}/upload | Upload HIS file (CSV/Excel) | Admin |
| PATCH | /api/audit/{id}/close | Lock session + run variance | Admin |
| GET | /sync/pull | Pull catalog delta for mobile | JWT |
| POST | /sync/push | Push scan records from mobile | JWT |
| GET | /api/reports/{id} | Fetch report (JSON + CSV) | JWT |
4 Sprints · 8 Weeks · Sprint Methodology
| ID | Task | Owner | Priority | Status | Notes |
|---|---|---|---|---|---|
| S1-01 | Initialize RN project + monorepo structure | Dev 1 | Critical | To Do | Nx or Turborepo, shared types package |
| S1-02 | Setup Express/TS API boilerplate | Dev 1 | Critical | To Do | ESLint, Prettier, Jest, Docker compose |
| S1-03 | PostgreSQL schema v1 + migrations | Dev 1 | Critical | To Do | users, roles, audit_sessions, zones, items |
| S1-04 | OAuth 2.0 login flow + JWT issuance | Dev 1 | Critical | To Do | passport.js or custom, refresh rotation |
| S1-05 | RBAC middleware + route guards | Dev 1 | High | To Do | role-based decorators for routes |
| S1-06 | Web login UI + SSO redirect flow | Dev 2 | High | To Do | React + react-router, token storage |
| S1-07 | Mobile login UI + biometric unlock | Dev 2 | High | To Do | react-native-biometrics, Keychain |
| S1-08 | Docker Compose for local dev env | Dev 1 | Medium | To Do | API + PG + Redis containers |
| S1-09 | CI pipeline (GitHub Actions) | Dev 1 | Medium | To Do | Lint → Test → Build → Docker push |
| ID | Task | Owner | Priority | Status | Notes |
|---|---|---|---|---|---|
| S2-01 | S3 upload endpoint (Multer → S3) | Dev 1 | Critical | To Do | Multipart stream, return 202 |
| S2-02 | BullMQ setup + IngestFile job | Dev 1 | Critical | To Do | Queue config, retry policy, DLQ |
| S2-03 | Ingestion worker — CSV/Excel parse | Dev 1 | Critical | To Do | csv-parser + exceljs, stream from S3 |
| S2-04 | Batch INSERT with pg COPY | Dev 1 | High | To Do | 50K+ rows performance |
| S2-05 | Audit session CRUD API | Dev 1 | High | To Do | State machine: DRAFT→READY→ACTIVE→CLOSED |
| S2-06 | Zone CRUD API | Dev 1 | Medium | To Do | Facility → Zone hierarchy |
| S2-07 | Dashboard — Audit session manager UI | Dev 2 | High | To Do | List, create, config, publish button |
| S2-08 | Dashboard — File upload + progress UI | Dev 2 | High | To Do | Drag-drop, progress bar, validation |
| S2-09 | Dashboard — Zone management UI | Dev 2 | Medium | To Do | CRUD form + zone tree view |
| S2-10 | Dashboard — User admin page | Dev 2 | Medium | To Do | Create user, assign role, deactivate |
| S2-11 | Variance threshold config API + UI | Dev 1 | Medium | To Do | Rules engine: minor/standard/critical |
| ID | Task | Owner | Priority | Status | Notes |
|---|---|---|---|---|---|
| S3-01 | WatermelonDB schema + models | Dev 1 | Critical | To Do | items, scan_records, zones, sessions |
| S3-02 | Sync Engine — pull endpoint | Dev 1 | Critical | To Do | GET /sync/pull?last_pulled_at= → delta |
| S3-03 | Sync Engine — push endpoint | Dev 1 | Critical | To Do | POST /sync/push + UUID dedup + additive merge |
| S3-04 | Mobile — catalog pull + offline store | Dev 1 | Critical | To Do | database.sync() integration |
| S3-05 | Mobile — barcode scanner UI | Dev 2 | Critical | To Do | Camera scanner + BT HID support |
| S3-06 | Mobile — scan record creation + additive logic | Dev 1 | High | To Do | uuidv4(), pending_sync status, qty increment |
| S3-07 | Mobile — zone selector UI | Dev 2 | High | To Do | Picker from local DB zones |
| S3-08 | Mobile — auto-push Sync Manager | Dev 1 | High | To Do | NetInfo listener + exponential backoff |
| S3-09 | Contract tests: Mobile ↔ Sync Engine | Dev 1 | High | To Do | Pact or snapshot-based |
| S3-10 | Sync concurrency load test | Dev 1 | Medium | To Do | Simulate 20+ devices pushing at once |
| ID | Task | Owner | Priority | Status | Notes |
|---|---|---|---|---|---|
| S4-01 | Variance calculation engine (close audit) | Dev 1 | Critical | To Do | SQL: expected - SUM(physical) → delta per batch |
| S4-02 | Financial leakage aggregation | Dev 1 | Critical | To Do | SUM(delta * unit_cost) by category/zone |
| S4-03 | Report API endpoints | Dev 1 | High | To Do | GET /reports/{id} → JSON + CSV download |
| S4-04 | CSV/Excel export service | Dev 1 | High | To Do | exceljs streaming write → S3 or direct |
| S4-05 | Dashboard — Reports UI + charts | Dev 2 | Critical | To Do | Recharts: bar, pie, trend line. Export btn |
| S4-06 | Dashboard — Executive summary view | Dev 2 | High | To Do | Read-only KPI cards, financial impact |
| S4-07 | Dashboard — Variance drilldown table | Dev 2 | High | To Do | Filter by zone, status, severity |
| S4-08 | Nginx config + SSL + rate limiting | Dev 1 | High | To Do | Production nginx.conf, certbot |
| S4-09 | AWS ECS deployment (Terraform/CDK) | Dev 1 | High | To Do | ECS tasks, RDS, S3, SQS provisioning |
| S4-10 | E2E testing — full audit cycle | Dev 1 | Critical | To Do | Upload → scan → sync → close → report |
| S4-11 | Append-only ledger / soft-delete impl | Dev 1 | Medium | To Do | Version column + updated_at trigger |
| S4-12 | Mobile — scan history UI + sync status | Dev 2 | Medium | To Do | List of scans with pending/synced badge |
Tasks that block other work — coordinate handoffs.
Sprint 1 → Sprint 2
Sprint 2 → Sprint 3
Sprint 3 → Sprint 4
| Developer | Sprint 1 | Sprint 2 | Sprint 3 | Sprint 4 | Total |
|---|---|---|---|---|---|
| Dev 1 (BE + Basic FE) | 7 tasks | 7 tasks | 8 tasks | 8 tasks | 30 tasks |
| Dev 2 (UI/UX FE) | 2 tasks | 4 tasks | 2 tasks | 4 tasks | 12 tasks |
| Senior (Oversight) | — | — | — | — | Reviews only |
Team Structure · Module Ownership · Roles & Responsibilities
Sprint timeboxes for planning · Daily standups · PR reviews by Senior
Each module has a primary owner. Senior Dev reviews all PRs.
RBAC Permissions · Page Field Specs · Mobile Modules · Web Modules · Database Schema
5 platform roles with hierarchical access levels
Highest privilege. Configures environment variables, API keys, models, feature flags, infrastructure settings. Full system + DevOps access.
Full system control. Manages pharmacies, users, audit sessions, configuration. Can access everything except infrastructure.
Pharmacy-level management. Creates audits, manages zones, reviews reports. Cannot manage users or system settings.
Field operator. Scans barcodes, enters quantities, syncs data. Read-only on reports. No admin access.
Read-only oversight. Views dashboards, reports, financial summaries. Cannot modify any data.
Create · Read · Update · Delete permissions per role per resource
| Resource / Action | ⚡ Super Admin | 🛡️ Admin | 📊 Manager | 📱 Auditor | 👁️ Executive | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| C | R | U | D | C | R | U | D | C | R | U | D | C | R | U | D | C | R | U | D | |
| 🏥 Pharmacies / Facilities | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | — | ⊘ | — | — | — | ◉ | — | — |
| 📍 Zones | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ⊘ | — | — | — | ◉ | — | — |
| 👤 Users | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ⊘ | — | — | — | ⊘ | ⊘ | — | — | — | — | — |
| 📝 Audit Sessions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | ⊘ | — | — | — | ◉ | — | — |
| 📤 HIS File Upload | ✓ | ✓ | — | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | — | — | — | — | — | — | — | — | — | — |
| 📦 HIS Items / Catalog | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | — | ✓ | — | — | — | ⊘ | — | — | — | ◉ | — | — |
| 🔍 Scan Records | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | — | ✓ | — | — | ✓ | ⊘ | ⊘ | — | — | — | — | — |
| 📊 Variance Data | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | — | ✓ | — | — | — | ⊘ | — | — | — | ◉ | — | — |
| 📈 Reports | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | — | — | — | ⊘ | — | — | — | ◉ | — | — |
| 📥 Export (CSV/Excel/PDF) | ✓ | ✓ | — | — | ✓ | ✓ | — | — | ✓ | ✓ | — | — | — | — | — | — | ✓ | ✓ | — | — |
| 📊 Dashboard (KPIs) | ✓ | ✓ | ✓ | — | — | ✓ | — | — | — | ✓ | — | — | — | ⊘ | — | — | — | ◉ | — | — |
| ⚙️ System Settings | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | ◉ | — | — | — | — | — | — | — | — | — | — |
| 🎚️ Variance Thresholds | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ◉ | — | — | — | — | — | — | — | — | — | — |
| 📜 Audit Trail / Logs | ✓ | ✓ | — | ✓ | — | ✓ | — | — | — | ◉ | — | — | — | — | — | — | — | ◉ | — | — |
| 🔔 Notifications | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | ✓ | ✓ | — | — | ⊘ | ⊘ | — | — | ◉ | — | — |
| 🔄 Sync Management | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | — | — | ◉ | — | — | — | ⊘ | — | — | — | — | — | — |
| 🔑 Environment Variables / Secrets | ✓ | ✓ | ✓ | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 🧠 Model / AI Configuration | ✓ | ✓ | ✓ | ✓ | — | ◉ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 🏗️ Infrastructure / Deployment | ✓ | ✓ | ✓ | ✓ | — | ◉ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 🚩 Feature Flags / Toggles | ✓ | ✓ | ✓ | ✓ | — | ◉ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 💾 Backup & Restore | ✓ | ✓ | ✓ | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 🔒 API Keys & Rate Limits | ✓ | ✓ | ✓ | ✓ | — | ◉ | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
Which screens and features each role can access
| Feature / Screen | ⚡ Super Admin | 🛡️ Admin | 📊 Manager | 📱 Auditor | 👁️ Executive |
|---|---|---|---|---|---|
| Web Dashboard Login | ✓ | ✓ | ✓ | — | ✓ |
| Mobile App Login | — | ✓ | ✓ | ✓ | — |
| Admin Dashboard | ✓ | ✓ | — | — | — |
| Manager Dashboard | ✓ | ✓ | ✓ | — | — |
| Executive Dashboard | ✓ | ✓ | — | — | ✓ |
| Pharmacy Management | ✓ | ✓ | ◉ | — | ◉ |
| Zone Management | ✓ | ✓ | ✓ | ◉ | ◉ |
| User Management | ✓ | ✓ | — | — | — |
| Audit Session Manager | ✓ | ✓ | ✓ | ◉ | ◉ |
| HIS File Upload | ✓ | ✓ | ✓ | — | — |
| Barcode Scanner (Mobile) | — | — | ✓ | ✓ | — |
| Manual Scan Entry (Mobile) | — | — | ✓ | ✓ | — |
| Scan History | ✓ | ✓ | ✓ | ⊘ | — |
| Sync Status | ✓ | ✓ | ◉ | ⊘ | — |
| Variance Analysis | ✓ | ✓ | ✓ | ◉ | ✓ |
| Reports & Analytics | ✓ | ✓ | ✓ | ◉ | ✓ |
| Export Center | ✓ | ✓ | ✓ | — | ✓ |
| Settings & Configuration | ✓ | ✓ | ◉ | — | — |
| Audit Trail / Activity Log | ✓ | ✓ | ◉ | — | ◉ |
| Notification Settings | ✓ | ✓ | ✓ | ⊘ | ◉ |
| Expiry Alert Management | ✓ | ✓ | ✓ | ◉ | ◉ |
| 🔧 Environment Variables Config | ✓ | — | — | — | — |
| 🤖 Model Configuration (AI/ML) | ✓ | — | — | — | — |
| 🚀 Feature Flags / Toggles | ✓ | ◉ | — | — | — |
| 🏢 Tenant / Organization Mgmt | ✓ | — | — | — | — |
| 📡 Infrastructure Monitoring | ✓ | — | — | — | — |
Every field on every page — type, validation, required status
React Native · iOS + Android · WatermelonDB · Offline-First
Email/password login, SSO redirect, biometric unlock (Face ID / Fingerprint), secure token storage in Keychain/Keystore.
Overview of assigned audit sessions, pending scans count, sync status indicator, quick-action cards for active audits.
Browse assigned audit sessions with status badges (DRAFT, READY, ACTIVE, CLOSED). Tap to enter scanning mode for active sessions.
Pick the zone you're auditing from the local DB list. Zones are synced from server. Each scan is tagged to the selected zone.
Camera-based barcode scanning (EAN-13, Code-128, QR) with Bluetooth HID scanner support. Auto-lookup from local catalog, quantity prompt, additive duplicate handling.
Manually enter barcode/product when scanner fails. Search catalog by name, select batch, enter quantity. Same additive logic applies.
View all scans for the current session. Shows product, qty, zone, timestamp, sync status badge (pending/synced/conflict). Swipe to edit qty.
Background sync engine with NetInfo listener. Auto-push when online, exponential backoff on failure. Shows queue depth and last sync timestamp.
Full offline capability. All scanning works without internet. Data stored in WatermelonDB (SQLite). Visual indicator shows offline status. Queues all changes for sync.
Highlights items nearing expiry during scan. Color-coded warnings: red (expired), amber (≤30 days), yellow (≤90 days). Push notifications for tracked items.
View profile, change password, manage biometric preferences, set notification preferences, view app version, clear local cache.
Receive real-time alerts for new audit assignments, sync failures, expiry warnings, and session status changes. Badge count on app icon.
React.js · Tailwind CSS · Recharts · Role-Based Views
Web login page with email/password, Google SSO, Azure AD integration. Redirect-based OAuth flow with PKCE. Session persistence with httpOnly cookies.
System-wide overview: total pharmacies, active audits, user counts, recent activity feed, system health indicators, quick-action buttons.
Pharmacy-scoped view: assigned pharmacy KPIs, active audit progress, zone completion rates, pending reviews, auditor performance metrics.
Read-only high-level view: financial impact summaries, cross-pharmacy comparisons, trend charts, leakage aggregation, compliance scores.
CRUD interface for pharmacies/facilities. Add, edit, deactivate pharmacies. View pharmacy details, zones, assigned users, audit history.
Create and manage zones within pharmacies. Tree-view hierarchy, zone codes, floor/building assignment, status toggle, sort ordering.
Create, edit, deactivate users. Assign roles (Super Admin/Admin/Manager/Auditor/Executive), map to pharmacies, reset passwords, view login history.
Full lifecycle management: create session, configure zones, upload HIS file, publish to auditors, monitor progress, close audit, approve results.
Drag-and-drop file upload with validation. Supports CSV/XLSX. Real-time progress bar, row count preview, error log display, re-upload capability.
Real-time view of active audit progress. Zone completion percentages, auditor activity feed, scan rate charts, WebSocket-powered live updates.
Detailed variance drilldown after audit close. Filter by zone, category, severity. Sortable table with shortage/overage/expired highlighting.
Interactive charts and reports. Bar charts for variance by zone, pie charts for category breakdown, trend lines for audit-over-audit comparison.
Download reports in multiple formats. Generate CSV, Excel (styled), PDF with letterhead. Scheduled report emails. Bulk export across audits.
System-wide settings: variance thresholds, notification channels, sync intervals, upload limits, GPS/photo toggles, audit trail retention.
Immutable activity log showing all user actions, data changes, login events. Filterable by user, action type, date range. Append-only — no deletions.
In-app notification panel. Real-time alerts for audit events, file processing status, sync errors, expiry warnings. Mark read/unread, notification preferences.
Manage all environment configurations: API keys, database URLs, third-party service credentials, runtime parameters. Masked values with reveal toggle. Change history tracking.
Configure AI/ML model endpoints, parameters, and thresholds. Manage model versions, A/B testing configs, inference settings, token budgets, and fallback strategies.
Enable/disable features per tenant, role, or environment. Gradual rollouts with percentage controls, scheduled activations, kill switches for emergencies.
Multi-tenant administration: create/manage organizations, configure tenant-specific settings, data isolation policies, billing tiers, storage quotas, and admin user provisioning.
Core tables · Column types · Primary & Foreign keys · Constraints
PharmaAudit — Developer Hub · Technical Flows & Sprint Worksheets
April 2026 · 4 Sprints · 3 Engineers · 42 Tasks