# harshendram/firstcommit-hack architecture

> Architecture diagram of the GitHub repository harshendram/firstcommit-hack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshendram/firstcommit-hack
- Repository: https://github.com/harshendram/firstcommit-hack

## Overview

Suraksha is a consent-aware home-care companion: watch and tablet signals or conversations enter its API, which coordinates agent responses, memory, proactive checks and policy-gated family escalation. Parents use the companion and privacy/audit views; family members get a calm dashboard, evidence-based Q&A and escalation responses. The README documents major subsystems and AWS integrations; sampled excerpts confirm selected API, escalation, state-refresh and watch messaging behavior, but do not expose every runtime call path, so uncertain wiring is omitted. The Explore world is a separate demo experience.

Main entry points: [`ally/app.py`](https://github.com/harshendram/firstcommit-hack/blob/main/ally/app.py) (Agent API), [`ally/agents/orchestrator.py`](https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/orchestrator.py) (Turn orchestrator), [`ally/escalation/service.py`](https://github.com/harshendram/firstcommit-hack/blob/main/ally/escalation/service.py) (Family escalation), [`ally/store/repo.py`](https://github.com/harshendram/firstcommit-hack/blob/main/ally/store/repo.py) (Single-table memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Care surfaces"]
  node_wearable["Wear OS watch"]
  node_parent_web["Parent web"]
  node_family_web["Family web"]
  node_command["Command views"]
  node_explore["Explore demo"]
end

subgraph group_runtime["Care runtime"]
  node_api["Agent API<br/>[app.py]"]
  node_orchestrator["Turn orchestrator<br/>[orchestrator.py]"]
  node_companion["Voice companion<br/>[companion.py]"]
  node_family_qa["Family Q&amp;A<br/>[family_qa.py]"]
  node_voice["Voice processing"]
end

subgraph group_safety["Policy and escalation"]
  node_consent["Consent guard"]
  node_scoring["Signal judgement"]
  node_proactive["Proactive care"]
  node_escalation["Family escalation<br/>[service.py]"]
end

subgraph group_memory["Memory and care"]
  node_memory_store[("Single-table memory<br/>[repo.py]")]
end

subgraph group_integrations["External services"]
  node_bedrock{{"Amazon Bedrock"}}
  node_transcribe{{"Amazon Transcribe"}}
  node_polly{{"Amazon Polly"}}
  node_dynamo[("Amazon DynamoDB")]
  node_eventbridge{{"Amazon EventBridge"}}
  node_step_functions{{"AWS Step Functions"}}
  node_push{{"Web Push"}}
end

node_parent(("Parent"))
node_family(("Family"))
node_nearby(("Nearby help"))

node_parent -->|"wears and speaks"| node_wearable
node_parent -->|"uses"| node_parent_web
node_family -->|"uses"| node_family_web
node_nearby -.->|"responds through"| node_family_web
node_wearable -->|"sends signals"| node_api
node_parent_web -->|"sends turns"| node_api
node_family_web -->|"asks and replies"| node_api
node_command -->|"views care status"| node_api
node_api -->|"dispatches turns"| node_orchestrator
node_orchestrator -->|"runs companion"| node_companion
node_orchestrator -->|"runs family Q&amp;A"| node_family_qa
node_orchestrator -->|"processes speech"| node_voice
node_companion -->|"invokes agent model"| node_bedrock
node_family_qa -->|"invokes agent model"| node_bedrock
node_voice -->|"transcribes speech"| node_transcribe
node_voice -->|"speaks replies"| node_polly
node_orchestrator -->|"guards tool calls"| node_consent
node_api -->|"authorizes dashboard"| node_consent
node_consent -->|"records audit"| node_memory_store
node_orchestrator -->|"reads and writes facts"| node_memory_store
node_api -->|"reads care records"| node_memory_store
node_eventbridge -->|"triggers sweep"| node_proactive
node_proactive -->|"checks due care"| node_memory_store
node_proactive -->|"judges signals"| node_scoring
node_scoring -->|"requests judgement"| node_bedrock
node_proactive -->|"starts escalation"| node_escalation
node_escalation -->|"starts workflow"| node_step_functions
node_step_functions -->|"dispatches callbacks"| node_escalation
node_escalation -->|"notifies contacts"| node_push
node_escalation -->|"updates lifecycle"| node_memory_store
node_explore -.->|"hosts gallery demo"| node_explore

click node_wearable "https://github.com/harshendram/firstcommit-hack/tree/main/wear-os/app/src/main/java/com/rakshak/wear"
click node_parent_web "https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/parent"
click node_family_web "https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/family"
click node_command "https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/command"
click node_explore "https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/explore"
click node_api "https://github.com/harshendram/firstcommit-hack/blob/main/ally/app.py"
click node_orchestrator "https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/orchestrator.py"
click node_companion "https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/companion.py"
click node_family_qa "https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/family_qa.py"
click node_voice "https://github.com/harshendram/firstcommit-hack/tree/main/ally/voice"
click node_consent "https://github.com/harshendram/firstcommit-hack/tree/main/ally/policy"
click node_scoring "https://github.com/harshendram/firstcommit-hack/tree/main/ally/scoring"
click node_proactive "https://github.com/harshendram/firstcommit-hack/tree/main/ally/proactive"
click node_escalation "https://github.com/harshendram/firstcommit-hack/blob/main/ally/escalation/service.py"
click node_memory_store "https://github.com/harshendram/firstcommit-hack/blob/main/ally/store/repo.py"

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_wearable,node_parent_web,node_family_web,node_command,node_explore toneBlue
class node_api,node_orchestrator,node_companion,node_family_qa,node_voice toneAmber
class node_consent,node_scoring,node_proactive,node_escalation toneMint
class node_memory_store toneRose
class node_bedrock,node_transcribe,node_polly,node_dynamo,node_eventbridge,node_step_functions,node_push,node_parent,node_family,node_nearby toneIndigo
```

## Components

### Care surfaces

- [Wear OS watch](https://github.com/harshendram/firstcommit-hack/tree/main/wear-os/app/src/main/java/com/rakshak/wear): `wear-os/app/src/main/java/com/rakshak/wear`
- [Parent web](https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/parent): `web/src/app/parent`
- [Family web](https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/family): `web/src/app/family`
- [Command views](https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/command): `web/src/app/command`
- [Explore demo](https://github.com/harshendram/firstcommit-hack/tree/main/web/src/app/explore): `web/src/app/explore`

### Care runtime

- [Agent API](https://github.com/harshendram/firstcommit-hack/blob/main/ally/app.py): `ally/app.py`
- [Turn orchestrator](https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/orchestrator.py): `ally/agents/orchestrator.py`
- [Voice companion](https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/companion.py): `ally/agents/companion.py`
- [Family Q&A](https://github.com/harshendram/firstcommit-hack/blob/main/ally/agents/family_qa.py): `ally/agents/family_qa.py`
- [Voice processing](https://github.com/harshendram/firstcommit-hack/tree/main/ally/voice): `ally/voice`

### Policy and escalation

- [Consent guard](https://github.com/harshendram/firstcommit-hack/tree/main/ally/policy): `ally/policy`
- [Signal judgement](https://github.com/harshendram/firstcommit-hack/tree/main/ally/scoring): `ally/scoring`
- [Proactive care](https://github.com/harshendram/firstcommit-hack/tree/main/ally/proactive): `ally/proactive`
- [Family escalation](https://github.com/harshendram/firstcommit-hack/blob/main/ally/escalation/service.py): `ally/escalation/service.py`

### Memory and care

- [Single-table memory](https://github.com/harshendram/firstcommit-hack/blob/main/ally/store/repo.py): `ally/store/repo.py`

### External services

- **Amazon Bedrock**
- **Amazon Transcribe**
- **Amazon Polly**
- **Amazon DynamoDB**
- **Amazon EventBridge**
- **AWS Step Functions**
- **Web Push**

### Other components

- **Parent**
- **Family**
- **Nearby help**

## Connections

- Parent → Wear OS watch: wears and speaks
- Parent → Parent web: uses
- Family → Family web: uses
- Nearby help → Family web: responds through
- Wear OS watch → Agent API: sends signals
- Parent web → Agent API: sends turns
- Family web → Agent API: asks and replies
- Command views → Agent API: views care status
- Agent API → Turn orchestrator: dispatches turns
- Turn orchestrator → Voice companion: runs companion
- Turn orchestrator → Family Q&A: runs family Q&A
- Turn orchestrator → Voice processing: processes speech
- Voice companion → Amazon Bedrock: invokes agent model
- Family Q&A → Amazon Bedrock: invokes agent model
- Voice processing → Amazon Transcribe: transcribes speech
- Voice processing → Amazon Polly: speaks replies
- Turn orchestrator → Consent guard: guards tool calls
- Agent API → Consent guard: authorizes dashboard
- Consent guard → Single-table memory: records audit
- Turn orchestrator → Single-table memory: reads and writes facts
- Agent API → Single-table memory: reads care records
- Amazon EventBridge → Proactive care: triggers sweep
- Proactive care → Single-table memory: checks due care
- Proactive care → Signal judgement: judges signals
- Signal judgement → Amazon Bedrock: requests judgement
- Proactive care → Family escalation: starts escalation
- Family escalation → AWS Step Functions: starts workflow
- AWS Step Functions → Family escalation: dispatches callbacks
- Family escalation → Web Push: notifies contacts
- Family escalation → Single-table memory: updates lifecycle
- Explore demo → Explore demo: hosts gallery demo