# jaynightmare/sofrs-ea-frontend architecture

> Architecture diagram of the GitHub repository jaynightmare/sofrs-ea-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaynightmare/sofrs-ea-frontend
- Repository: https://github.com/jaynightmare/sofrs-ea-frontend

## Overview

1. **Repository shape**
   - This repo is a frontend-only monorepo with two independent client apps:
     - `Desktop/employee-access/`: Electron desktop app for kiosk/admin/employee/visitor workflows.
     - `Mobile/employee-access/`: Expo/React Native mobile app for onboarding and badge-related flows.
   - The shared backend is not in this repo; both apps are UI/orchestration layers that call into external APIs/services.

2. **System boundary**
   - The key architectural boundary is **desktop vs mobile**:
     - Desktop is the operational access terminal, likely attached to a camera and running continuously.
     - Mobile is the user-facing companion app for setup, identity verification, QR/face scan, and badge display.
   - The README explicitly says backend face recognition is handled elsewhere, while the frontend provides detections/screenshot-based inputs.

3. **Desktop app runtime**
   - The desktop app is built on **Electron + Vite** with separate build/runtime entry points:
     - `src/main.ts` for the Electron main process.
     - `src/preload.ts` for the secure bridge between main and renderer.
     - `src/renderer.ts` for the browser-side UI entry.
   - This split is important for architecture diagrams because native capabilities, IPC, and UI rendering live in different process boundaries.

4. **Desktop UI composition**
   - Desktop UI is organized into reusable components under `src/components/` and screen-level flows under `src/pages/`.
   - Components such as `kiosk-layout`, `loading-overlay`, `face`, `chooser`, `music`, and `icons` provide shared UI behavior across screens.
   - Screen pages are grouped by function: `home`, `employee`, `visitor`, `main-screen`, `error`, plus kiosk-specific and admin-specific pages.

5. **Desktop operational flows**
   - The most important desktop workflows are:
     - **Kiosk flow**: `idle`, `scan`, `register`, `approved`, `denied`, `help`, `settings`, `pin-modal`.
     - **Admin flow**: `dashboard`, `employee-manager`, `visitor-manager`.
   - These screens suggest a state-machine-like user journey: idle → capture/scan → verify → approve/deny, with fallback/help/settings branches.

6. **Desktop service layer**
   - Business logic is separated into `src/services/`:
     - `face-detector.ts` for camera/face boundary detection.
     - `verification.ts` for identity/approval logic.
     - `settings.ts` for persisted configuration.
     - `weather.ts` for auxiliary external data shown in the UI.
   - `verification.test.ts` shows the verification logic is testable in isolation, which indicates business rules are not hardwired into the UI.

7. **Desktop external integration**
   - `src/api.ts` is the main frontend API boundary to backend services.
   - The likely data path is: camera input/face detection → verification/service logic → API request or screenshot payload → backend response → kiosk/admin UI state.
   - `src/music/bg-music.mp3` and `music.ts` indicate the kiosk can include ambient audio as part of the user experience.

8. **Desktop packaging/tooling**
   - Build orchestration is handled with multiple configs: `vite.main.config.ts`, `vite.preload.config.ts`, `vite.renderer.config.ts`, `forge.config.ts`, and `webpack.config.js`.
   - This implies the app is packaged/distributed as a desktop executable rather than served as a web app.

9. **Mobile app runtime and navigation**
   - The mobile app uses **Expo + Expo Router**, with route-based navigation under `app/`.
   - The root layout (`app/_layout.tsx`) and dashboard tab layout (`app/(dashboard)/_layout.tsx`) define the navigation structure.
   - This means screen transitions are driven by the file system router, not a manually managed navigation registry.

10. **Mobile onboarding and verification flow**
    - The mobile app centers on a linear onboarding/verification journey:
      - `index` / entry screen
      - `identity-verification`
      - `face-setup`
      - `face-scan`
      - `relay-capture`
      - `scan-qr`
      - `setup-success`
    - These screens suggest a staged process where the app collects identity, face data, and pairing/relay information before completion.

11. **Mobile dashboard and badge generation**
    - The `(dashboard)` route group contains `index.tsx` and `badge.tsx`, indicating a post-setup area for user status and badge display/generation.
    - This is a separate user-facing area from onboarding, so a diagram should show it as the “post-registration” branch.

12. **Mobile shared state and integration**
    - `contexts/user-context.tsx` holds cross-screen user state, which is the main state-sharing boundary in the app.
    - `lib/api.ts` and `lib/deeplink.ts` are the main integration points:
      - API calls to backend services.
      - Deep link handling to connect external flows back into the app.

13. **Mobile presentation layer**
    - Shared UI is centralized in `components/` and theme constants/hooks:
      - `themed-text`, `themed-view`, `FingerprintAnimation`, `haptic-tab`, and `ui/*`.
      - `constants/theme.ts` and `hooks/use-color-scheme*` indicate theme-aware rendering.
    - The app is designed to adapt to light/dark or platform-specific styling, but the architectural role is still presentation-only.

14. **Cross-app relationship**
    - The two apps are complementary rather than duplicated:
      - Desktop manages live access control and kiosk/admin operations.
      - Mobile handles enrollment and badge-related workflows.
    - If you are drawing a system diagram, place the backend/services in the middle, with desktop and mobile as two separate clients consuming different APIs and user journeys.

Main entry points: [`Mobile/employee-access/app`](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app) (Onboarding flow), [`Desktop/employee-access/src/renderer.ts`](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/renderer.ts) (Renderer entry), [`Desktop/employee-access/src/services`](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/services) (Service layer), [`Mobile/employee-access/app/(dashboard)`](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app/(dashboard)) (Dashboard area)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_desktop_main["Electron main<br/>runtime entry<br/>[main.ts]"]
  node_desktop_preload["Preload bridge<br/>ipc bridge<br/>[preload.ts]"]
  node_desktop_renderer["Renderer entry<br/>ui entry<br/>[renderer.ts]"]
  node_desktop_pages["Desktop pages<br/>screen flows"]
  node_desktop_components["UI components<br/>shared views"]
  node_desktop_services["Service layer<br/>business logic"]
  node_desktop_api["API client<br/>integration<br/>[api.ts]"]
  node_desktop_music["Kiosk audio<br/>asset<br/>[bg-music.mp3]"]
  node_desktop_build["Build configs<br/>tooling"]
end

subgraph group_mobile["Mobile app"]
  node_mobile_root["App router<br/>navigation entry<br/>[_layout.tsx]"]
  node_mobile_dashboard["Dashboard area<br/>post-setup routes"]
  node_mobile_onboarding["Onboarding flow<br/>route flow"]
  node_mobile_state["User context<br/>shared state<br/>[user-context.tsx]"]
  node_mobile_components["Shared UI<br/>presentation"]
  node_mobile_theme["Theme hooks<br/>presentation<br/>[theme.ts]"]
  node_mobile_api["API client<br/>integration<br/>[api.ts]"]
  node_mobile_deeplink["Deep links<br/>integration<br/>[deeplink.ts]"]
end

subgraph group_external["External services"]
  node_backend[("Backend services<br/>external backend")]
  node_device_io(("Camera and sensors<br/>device input"))
end

node_desktop_main -->|"loads"| node_desktop_preload
node_desktop_preload -->|"bridges"| node_desktop_renderer
node_desktop_renderer -->|"renders"| node_desktop_pages
node_desktop_renderer -->|"uses"| node_desktop_components
node_desktop_pages -->|"delegates"| node_desktop_services
node_desktop_services -->|"calls"| node_desktop_api
node_desktop_services -->|"consumes"| node_device_io
node_desktop_renderer -->|"plays"| node_desktop_music
node_desktop_build -->|"packages"| node_desktop_main
node_desktop_build -->|"bundles"| node_desktop_renderer
node_mobile_root -->|"routes to"| node_mobile_onboarding
node_mobile_root -->|"routes to"| node_mobile_dashboard
node_mobile_onboarding -->|"shares state"| node_mobile_state
node_mobile_dashboard -->|"reads state"| node_mobile_state
node_mobile_onboarding -->|"calls"| node_mobile_api
node_mobile_dashboard -->|"calls"| node_mobile_api
node_mobile_onboarding -->|"handles"| node_mobile_deeplink
node_mobile_components -->|"styled by"| node_mobile_theme
node_mobile_onboarding -->|"uses"| node_device_io
node_mobile_api -->|"requests"| node_backend
node_desktop_api -->|"requests"| node_backend
node_desktop_services -->|"verifies via"| node_backend

click node_desktop_main "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/main.ts"
click node_desktop_preload "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/preload.ts"
click node_desktop_renderer "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/renderer.ts"
click node_desktop_pages "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/pages"
click node_desktop_components "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/components"
click node_desktop_services "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/services"
click node_desktop_api "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/api.ts"
click node_desktop_music "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/music/bg-music.mp3"
click node_desktop_build "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/vite.renderer.config.ts"
click node_mobile_root "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/app/_layout.tsx"
click node_mobile_dashboard "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app/(dashboard)"
click node_mobile_onboarding "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app"
click node_mobile_state "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/contexts/user-context.tsx"
click node_mobile_components "https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/components"
click node_mobile_theme "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/constants/theme.ts"
click node_mobile_api "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/lib/api.ts"
click node_mobile_deeplink "https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/lib/deeplink.ts"

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_desktop_main,node_desktop_preload,node_desktop_renderer,node_desktop_pages,node_desktop_components,node_desktop_services,node_desktop_api,node_desktop_music,node_desktop_build toneBlue
class node_mobile_root,node_mobile_dashboard,node_mobile_onboarding,node_mobile_state,node_mobile_components,node_mobile_theme,node_mobile_api,node_mobile_deeplink toneAmber
class node_backend,node_device_io toneMint
```

## Components

### Desktop app

Electron/Vite kiosk and admin client

- [Electron main](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/main.ts): runtime entry · Desktop app main-process entrypoint · `Desktop/employee-access/src/main.ts`
- [Preload bridge](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/preload.ts): ipc bridge · Secure bridge between main and renderer · `Desktop/employee-access/src/preload.ts`
- [Renderer entry](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/renderer.ts): ui entry · Browser-side desktop UI bootstrap · `Desktop/employee-access/src/renderer.ts`
- [Desktop pages](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/pages): screen flows · Kiosk, admin, employee, visitor, and error screens · `Desktop/employee-access/src/pages`
- [UI components](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/components): shared views · Reusable kiosk and display components · `Desktop/employee-access/src/components`
- [Service layer](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Desktop/employee-access/src/services): business logic · Face detection, verification, settings, and weather logic · `Desktop/employee-access/src/services`
- [API client](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/api.ts): integration · Frontend boundary for backend requests · `Desktop/employee-access/src/api.ts`
- [Kiosk audio](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/src/music/bg-music.mp3): asset · Ambient music used by the kiosk experience · `Desktop/employee-access/src/music/bg-music.mp3`
- [Build configs](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Desktop/employee-access/vite.renderer.config.ts): tooling · Vite, Forge, and packaging configuration · `Desktop/employee-access/vite.renderer.config.ts`

### Mobile app

Expo/React Native onboarding and badge client

- [App router](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/app/_layout.tsx): navigation entry · Expo Router root layout and route composition · `Mobile/employee-access/app/_layout.tsx`
- [Dashboard area](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app/(dashboard)): post-setup routes · Signed-in area for badge and status views · `Mobile/employee-access/app/(dashboard)`
- [Onboarding flow](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/app): route flow · Identity, face, QR, relay, and setup screens · `Mobile/employee-access/app`
- [User context](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/contexts/user-context.tsx): shared state · Cross-screen app state for user onboarding · `Mobile/employee-access/contexts/user-context.tsx`
- [Shared UI](https://github.com/jaynightmare/sofrs-ea-frontend/tree/master/Mobile/employee-access/components): presentation · Themed text, views, animations, and UI primitives · `Mobile/employee-access/components`
- [Theme hooks](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/constants/theme.ts): presentation · Color scheme and theme constants · `Mobile/employee-access/constants/theme.ts`
- [API client](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/lib/api.ts): integration · Backend API boundary for mobile flows · `Mobile/employee-access/lib/api.ts`
- [Deep links](https://github.com/jaynightmare/sofrs-ea-frontend/blob/master/Mobile/employee-access/lib/deeplink.ts): integration · Deep-link handling for external handoffs · `Mobile/employee-access/lib/deeplink.ts`

### External services

Backend and device-facing dependencies outside this repo

- **Backend services**: external backend · External APIs for verification, identity, and badge-related operations
- **Camera and sensors**: device input · Desktop camera/face input and mobile capture flows

## Connections

- Electron main → Preload bridge: loads · Main process exposes safe renderer bridge
- Preload bridge → Renderer entry: bridges · Preload connects native capabilities to UI
- Renderer entry → Desktop pages: renders · Page-level kiosk and admin screens
- Renderer entry → UI components: uses · Shared UI building blocks
- Desktop pages → Service layer: delegates · Screens rely on verification and settings logic
- Service layer → API client: calls · Business logic reaches external backend APIs
- Service layer → Camera and sensors: consumes · Face detection and capture inputs
- Renderer entry → Kiosk audio: plays · Kiosk audio is part of the UI experience
- Build configs → Electron main: packages · Build pipeline produces desktop runtime artifacts
- Build configs → Renderer entry: bundles · Renderer is built separately
- App router → Onboarding flow: routes to · File-based onboarding screens
- App router → Dashboard area: routes to · Dashboard route group after setup
- Onboarding flow → User context: shares state · Flow state is coordinated through context
- Dashboard area → User context: reads state · Post-setup screens reuse user context
- Onboarding flow → API client: calls · Enrollment and verification data goes to backend
- Dashboard area → API client: calls · Badge/status screens fetch backend data
- Onboarding flow → Deep links: handles · External handoffs return via deep links
- Shared UI → Theme hooks: styled by · Presentation adapts to theme and scheme
- Onboarding flow → Camera and sensors: uses · Face and QR capture depend on device input
- API client → Backend services: requests · Mobile client consumes external services
- API client → Backend services: requests · Desktop client consumes external services
- Service layer → Backend services: verifies via · Verification logic is mediated by backend responses
