How jaynightmare/sofrs-ea-frontend works
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: app Onboarding flow · renderer.ts Renderer entry · services Service layer · (dashboard) Dashboard area
Components 19
Desktop app
Electron/Vite kiosk and admin client
- Electron main · Desktop app main-process entrypoint
Desktop/employee-access/src/main.ts - Preload bridge · Secure bridge between main and renderer
Desktop/employee-access/src/preload.ts - Renderer entry · Browser-side desktop UI bootstrap
Desktop/employee-access/src/renderer.ts - Desktop pages · Kiosk, admin, employee, visitor, and error screens
Desktop/employee-access/src/pages - UI components · Reusable kiosk and display components
Desktop/employee-access/src/components - Service layer · Face detection, verification, settings, and weather logic
Desktop/employee-access/src/services - API client · Frontend boundary for backend requests
Desktop/employee-access/src/api.ts - Kiosk audio · Ambient music used by the kiosk experience
Desktop/employee-access/src/music/bg-music.mp3 - Build configs · Vite, Forge, and packaging configuration
Desktop/employee-access/vite.renderer.config.ts
Mobile app
Expo/React Native onboarding and badge client
- App router · Expo Router root layout and route composition
Mobile/employee-access/app/_layout.tsx - Dashboard area · Signed-in area for badge and status views
Mobile/employee-access/app/(dashboard) - Onboarding flow · Identity, face, QR, relay, and setup screens
Mobile/employee-access/app - User context · Cross-screen app state for user onboarding
Mobile/employee-access/contexts/user-context.tsx - Shared UI · Themed text, views, animations, and UI primitives
Mobile/employee-access/components - Theme hooks · Color scheme and theme constants
Mobile/employee-access/constants/theme.ts - API client · Backend API boundary for mobile flows
Mobile/employee-access/lib/api.ts - Deep links · 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 APIs for verification, identity, and badge-related operations
- Camera and sensors · Desktop camera/face input and mobile capture flows
Connections 22
- 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