# devi-sivakumar-ds/finsight architecture

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

- Interactive diagram: https://gitdiagram.com/devi-sivakumar-ds/finsight
- Repository: https://github.com/devi-sivakumar-ds/finsight

## Overview

#### Purpose and entry points
FinSight is an Expo/React Native research prototype for accessible, voice-first mock check deposits. The participant app starts at `App.tsx`, which mounts navigation in `src/navigation/AppNavigator.tsx`. Its companion operator system is a browser dashboard served by `wizard-dashboard/server.js`, with UI assets in `wizard-dashboard/public/`.

#### Study-mode control boundary
The app is explicitly configured for research-stage Wizard of Oz control in `src/config/studyMode.ts`. In this mode, the mobile client owns rendering, speech, feedback, navigation, and local deposit state; a human operator decides ambiguous conversational, capture, OCR, and confirmation outcomes. This separates interaction evaluation from unreliable autonomous perception or language decisions.

#### Mobile deposit workflow
The principal task is a staged navigation flow: home/onboarding, deposit overview and privacy, account selection, check preparation/capture, OCR review, amount entry, confirmation, then success or recovery. The deposit-specific navigator is `src/navigation/DepositNavigator.tsx`; representative stateful stages are `src/screens/CheckCaptureScreen.tsx`, `src/screens/OCRProcessingScreen.tsx`, and `src/screens/ConfirmationScreen.tsx`. `src/screens/ErrorScreen.tsx` provides a recovery boundary rather than silently failing.

#### Wizard command and synchronization loop
The app-side WebSocket client in `src/services/wizardClient.ts` connects to the relay and exchanges structured session, state, and event messages. `src/services/wizardExecutor.ts` maps received operator commands into app actions, while `src/services/wizardState.ts` maintains the reportable session/deposit snapshot. Shared protocol/state contracts live in `src/types/wizard.ts` and command definitions in `src/utils/wizardCommands.ts`. This continuous app-to-dashboard state reporting is the main anti-drift mechanism.

#### Operator dashboard and relay infrastructure
`wizard-dashboard/server.js` hosts the dashboard, relays WebSocket traffic between operator and app clients, and persists local session logs. The operator-facing dashboard is a lightweight browser application rooted at `wizard-dashboard/public/index.html` with behavior in `wizard-dashboard/public/app.js`. The mobile app therefore requires reachability to the dashboard server; Android USB workflows use `scripts/wizard-android-usb.sh` to reverse the relevant local ports.

#### Interaction-feedback services
Voice is a cross-cutting runtime layer: `src/contexts/VoiceSettingsContext.tsx` provides user settings, and `src/hooks/useAlwaysOnVoice.ts` / `src/hooks/useTTS.ts` integrate continuous interaction and spoken output. Service boundaries isolate platform or simulated capabilities: `src/services/ttsService.ts`, `src/services/sttService.ts`, and `src/services/hapticsService.ts`. Capture feedback is similarly encapsulated in `src/services/captureSoundService.ts` and `src/components/VisualMic.tsx`.

#### Autonomous-capability seams and mock domain backend
The codebase retains separable automation seams for future/non-WoZ operation: camera/snapshot guidance in `src/services/geometryDetection.ts` and `src/services/snapshotAnalysis.ts`, OCR simulation/extraction in `src/services/ocrService.ts`, and intent handling in `src/services/intentService.ts`. Banking actions are intentionally non-production and pass through `src/services/mockBankingAPI.ts`; account choices are local fixture data in `src/data/accountProfiles.ts`. No real banking integration is indicated.

Main entry points: [`src/services/wizardClient.ts`](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardClient.ts) (Wizard client), [`src/navigation/DepositNavigator.tsx`](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/navigation/DepositNavigator.tsx) (Deposit workflow), [`wizard-dashboard/server.js`](https://github.com/devi-sivakumar-ds/finsight/blob/main/wizard-dashboard/server.js) (Dashboard relay), [`src/screens/CheckCaptureScreen.tsx`](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/CheckCaptureScreen.tsx) (Check capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile participant app"]
  node_app["App entry<br/>Expo entry<br/>[App.tsx]"]
  node_app_nav["App navigator<br/>navigation root<br/>[AppNavigator.tsx]"]
  node_deposit_nav["Deposit workflow<br/>staged navigator"]
  node_capture["Check capture<br/>screen"]
  node_ocr_review["OCR review<br/>screen"]
  node_confirmation["Confirmation<br/>screen"]
  node_recovery["Recovery<br/>error screen<br/>[ErrorScreen.tsx]"]
  node_automation_seams["Automation seams<br/>simulated capabilities"]
  node_mock_banking[("Mock banking<br/>domain backend<br/>[mockBankingAPI.ts]")]
end

subgraph group_wizard["Wizard control"]
  node_study_mode["Study mode<br/>research config<br/>[studyMode.ts]"]
  node_wizard_client{{"Wizard client<br/>WebSocket client<br/>[wizardClient.ts]"}}
  node_wizard_executor["Command executor<br/>action mapper<br/>[wizardExecutor.ts]"]
  node_wizard_state[("Session state<br/>state store<br/>[wizardState.ts]")]
  node_wizard_contracts["Wizard protocol<br/>shared contracts<br/>[wizard.ts]"]
end

subgraph group_operator["Operator dashboard"]
  node_dashboard_ui["Operator UI<br/>browser dashboard<br/>[app.js]"]
  node_relay{{"Dashboard relay<br/>Node server<br/>[server.js]"}}
  node_usb_tunnel["Android USB tunnel<br/>port forwarding script"]
end

subgraph group_feedback["Interaction feedback"]
  node_voice_settings["Voice settings<br/>context provider"]
  node_voice_runtime["Always-on voice<br/>voice hook"]
  node_speech_services["Speech services<br/>platform services<br/>[ttsService.ts]"]
end

node_app -->|"mounts"| node_app_nav
node_app_nav -->|"enters deposit task"| node_deposit_nav
node_deposit_nav -->|"capture stage"| node_capture
node_capture -->|"capture result"| node_ocr_review
node_ocr_review -->|"reviewed amount"| node_confirmation
node_deposit_nav -->|"failure path"| node_recovery
node_study_mode -.->|"enables WoZ sync"| node_wizard_client
node_wizard_state -->|"reports snapshot"| node_wizard_client
node_wizard_client -->|"WebSocket state and events"| node_relay
node_relay -->|"operator commands"| node_wizard_client
node_wizard_client -->|"received commands"| node_wizard_executor
node_wizard_executor -->|"drives app actions"| node_deposit_nav
node_wizard_contracts -.->|"message contracts"| node_wizard_client
node_dashboard_ui -->|"operator WebSocket"| node_relay
node_usb_tunnel -.->|"Android reachability"| node_relay
node_voice_settings -->|"configures"| node_voice_runtime
node_voice_runtime -->|"uses speech I/O"| node_speech_services
node_deposit_nav -.->|"voice guidance"| node_voice_runtime
node_capture -.->|"guidance and analysis"| node_automation_seams
node_ocr_review -.->|"OCR seam"| node_automation_seams
node_confirmation -->|"submits mock deposit"| node_mock_banking

click node_app "https://github.com/devi-sivakumar-ds/finsight/blob/main/App.tsx"
click node_app_nav "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/navigation/AppNavigator.tsx"
click node_deposit_nav "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/navigation/DepositNavigator.tsx"
click node_capture "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/CheckCaptureScreen.tsx"
click node_ocr_review "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/OCRProcessingScreen.tsx"
click node_confirmation "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/ConfirmationScreen.tsx"
click node_recovery "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/ErrorScreen.tsx"
click node_study_mode "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/config/studyMode.ts"
click node_wizard_client "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardClient.ts"
click node_wizard_executor "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardExecutor.ts"
click node_wizard_state "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardState.ts"
click node_wizard_contracts "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/types/wizard.ts"
click node_dashboard_ui "https://github.com/devi-sivakumar-ds/finsight/blob/main/wizard-dashboard/public/app.js"
click node_relay "https://github.com/devi-sivakumar-ds/finsight/blob/main/wizard-dashboard/server.js"
click node_usb_tunnel "https://github.com/devi-sivakumar-ds/finsight/blob/main/scripts/wizard-android-usb.sh"
click node_voice_settings "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/contexts/VoiceSettingsContext.tsx"
click node_voice_runtime "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/hooks/useAlwaysOnVoice.ts"
click node_speech_services "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/ttsService.ts"
click node_automation_seams "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/geometryDetection.ts"
click node_mock_banking "https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/mockBankingAPI.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_app,node_app_nav,node_deposit_nav,node_capture,node_ocr_review,node_confirmation,node_recovery,node_automation_seams,node_mock_banking toneBlue
class node_study_mode,node_wizard_client,node_wizard_executor,node_wizard_state,node_wizard_contracts toneAmber
class node_dashboard_ui,node_relay,node_usb_tunnel toneMint
class node_voice_settings,node_voice_runtime,node_speech_services toneRose
```

## Components

### Mobile participant app

Expo/React Native deposit study client.

- [App entry](https://github.com/devi-sivakumar-ds/finsight/blob/main/App.tsx): Expo entry · `App.tsx`
- [App navigator](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/navigation/AppNavigator.tsx): navigation root · `src/navigation/AppNavigator.tsx`
- [Deposit workflow](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/navigation/DepositNavigator.tsx): staged navigator · Routes deposit stages through success or recovery. · `src/navigation/DepositNavigator.tsx`
- [Check capture](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/CheckCaptureScreen.tsx): screen · `src/screens/CheckCaptureScreen.tsx`
- [OCR review](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/OCRProcessingScreen.tsx): screen · `src/screens/OCRProcessingScreen.tsx`
- [Confirmation](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/ConfirmationScreen.tsx): screen · `src/screens/ConfirmationScreen.tsx`
- [Recovery](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/screens/ErrorScreen.tsx): error screen · Explicit recovery boundary for failed stages. · `src/screens/ErrorScreen.tsx`
- [Automation seams](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/geometryDetection.ts): simulated capabilities · Future camera guidance, OCR, and intent handling boundary. · `src/services/geometryDetection.ts`
- [Mock banking](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/mockBankingAPI.ts): domain backend · Non-production banking actions backed by local account fixtures. · `src/services/mockBankingAPI.ts`

### Wizard control

Research-mode command and state synchronization.

- [Study mode](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/config/studyMode.ts): research config · Enables Wizard of Oz control boundary. · `src/config/studyMode.ts`
- [Wizard client](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardClient.ts): WebSocket client · Reports session state and receives relay messages. · `src/services/wizardClient.ts`
- [Command executor](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardExecutor.ts): action mapper · Maps operator commands into app actions. · `src/services/wizardExecutor.ts`
- [Session state](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/wizardState.ts): state store · Maintains reportable session and deposit snapshot. · `src/services/wizardState.ts`
- [Wizard protocol](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/types/wizard.ts): shared contracts · `src/types/wizard.ts`

### Operator dashboard

Browser UI and WebSocket relay.

- [Operator UI](https://github.com/devi-sivakumar-ds/finsight/blob/main/wizard-dashboard/public/app.js): browser dashboard · `wizard-dashboard/public/app.js`
- [Dashboard relay](https://github.com/devi-sivakumar-ds/finsight/blob/main/wizard-dashboard/server.js): Node server · Serves the dashboard, relays WebSockets, and persists local logs. · `wizard-dashboard/server.js`
- [Android USB tunnel](https://github.com/devi-sivakumar-ds/finsight/blob/main/scripts/wizard-android-usb.sh): port forwarding script · Reverses local dashboard ports for Android USB workflows. · `scripts/wizard-android-usb.sh`

### Interaction feedback

Voice, haptic, and capture feedback runtime.

- [Voice settings](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/contexts/VoiceSettingsContext.tsx): context provider · `src/contexts/VoiceSettingsContext.tsx`
- [Always-on voice](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/hooks/useAlwaysOnVoice.ts): voice hook · Continuous interaction and spoken output integration. · `src/hooks/useAlwaysOnVoice.ts`
- [Speech services](https://github.com/devi-sivakumar-ds/finsight/blob/main/src/services/ttsService.ts): platform services · Text-to-speech and speech-to-text boundary. · `src/services/ttsService.ts`

## Connections

- App entry → App navigator: mounts
- App navigator → Deposit workflow: enters deposit task
- Deposit workflow → Check capture: capture stage
- Check capture → OCR review: capture result
- OCR review → Confirmation: reviewed amount
- Deposit workflow → Recovery: failure path
- Study mode → Wizard client: enables WoZ sync
- Session state → Wizard client: reports snapshot
- Wizard client → Dashboard relay: WebSocket state and events
- Dashboard relay → Wizard client: operator commands
- Wizard client → Command executor: received commands
- Command executor → Deposit workflow: drives app actions
- Wizard protocol → Wizard client: message contracts
- Operator UI → Dashboard relay: operator WebSocket
- Android USB tunnel → Dashboard relay: Android reachability
- Voice settings → Always-on voice: configures
- Always-on voice → Speech services: uses speech I/O
- Deposit workflow → Always-on voice: voice guidance
- Check capture → Automation seams: guidance and analysis
- OCR review → Automation seams: OCR seam
- Confirmation → Mock banking: submits mock deposit