# hushh-labs/hushh-research architecture

> Architecture diagram of the GitHub repository hushh-labs/hushh-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hushh-labs/hushh-research
- Repository: https://github.com/hushh-labs/hushh-research

## Overview

Hussh is a consent-first private-agent platform. A user enters through the web/mobile experience, reaches the FastAPI service, and uses scoped identity and consent to access private-agent capabilities; results may involve PKM data or connected systems. Major documented branches include One and its specialists, voice, A2A/MCP, financial intelligence, consent management, and location/wallet features. Source excerpts establish several service and storage links; other capability links are documented by the README, and unsampled wiring is not inferred.

Main entry points: [`consent-protocol/hushh_mcp/agents/one`](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/agents/one) (One Agent), [`consent-protocol/api/routes`](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/api/routes) (API Routes), [`consent-protocol/server.py`](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/server.py) (FastAPI Service), [`hushh-webapp`](https://github.com/hushh-labs/hushh-research/tree/main/hushh-webapp) (Web And Mobile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web And Mobile"]
  node_marketplace_ria["Marketplace And RIA<br/>[marketplace.py]"]
end

subgraph group_trust_api["API And Trust"]
  node_api["FastAPI Service<br/>[server.py]"]
  node_routes["API Routes"]
  node_identity["Identity And Auth<br/>[middleware.py]"]
  node_consent["Consent Protocol"]
end

subgraph group_agents["Private Agents"]
  node_one["One Agent"]
  node_kai["Kai Finance<br/>[debate_engine.py]"]
  node_specialists["Nav And KYC"]
  node_voice["One Voice"]
  node_adk["ADK And A2A"]
  node_mcp["MCP Surface"]
  node_location_wallet["Location And Wallet"]
end

subgraph group_knowledge["Knowledge And Connectors"]
  node_db[("Postgres Access<br/>[db_client.py]")]
  node_pkm["PKM Storage API"]
  node_pkm_service["PKM Service"]
  node_drive_share["Drive Sharing<br/>[drive_sharing.py]"]
  node_drive_live["Live Drive Queries"]
  node_drive_ingest["Drive Ingestion"]
  node_google_drive["Google Drive"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"requests"| node_api
node_api -->|"registers"| node_routes
node_routes -.->|"protects"| node_identity
node_identity -->|"validates scopes"| node_consent
node_consent -->|"reads metadata"| node_db
node_routes -.->|"serves PKM"| node_pkm
node_pkm -->|"delegates"| node_pkm_service
node_routes -->|"serves sharing"| node_drive_share
node_drive_share -.->|"runs query"| node_drive_live
node_drive_ingest -->|"fetches content"| node_google_drive
node_user -->|"converses"| node_one
node_one -->|"summons finance"| node_kai
node_one -->|"summons specialists"| node_specialists
node_one -->|"offers voice"| node_voice
node_one -->|"uses delegation"| node_adk
node_api -->|"exposes developer surface"| node_mcp
node_user -->|"uses location"| node_location_wallet
node_user -->|"uses workflows"| node_marketplace_ria

click node_web "https://github.com/hushh-labs/hushh-research/tree/main/hushh-webapp"
click node_api "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/server.py"
click node_routes "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/api/routes"
click node_identity "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/middleware.py"
click node_consent "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/consent_listener.py"
click node_db "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/db/db_client.py"
click node_one "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/agents/one"
click node_kai "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/agents/kai/debate_engine.py"
click node_specialists "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/agents"
click node_voice "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/one_voice"
click node_adk "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/adk_bridge"
click node_mcp "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/mcp_modules"
click node_pkm "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/pkm_routes_shared.py"
click node_pkm_service "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/personal_knowledge_model_service.py"
click node_drive_share "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/drive_sharing.py"
click node_drive_live "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/drive_live_query_service.py"
click node_drive_ingest "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/drive_ingestion_service.py"
click node_google_drive "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/google_drive_adapter.py"
click node_location_wallet "https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/api/routes/one"
click node_marketplace_ria "https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/marketplace.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_web,node_marketplace_ria,node_user toneBlue
class node_api,node_routes,node_identity,node_consent toneAmber
class node_one,node_kai,node_specialists,node_voice,node_adk,node_mcp,node_location_wallet toneMint
class node_db,node_pkm,node_pkm_service,node_drive_share,node_drive_live,node_drive_ingest,node_google_drive toneRose
```

## Components

### User Experience

- [Web And Mobile](https://github.com/hushh-labs/hushh-research/tree/main/hushh-webapp): `hushh-webapp`
- [Marketplace And RIA](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/marketplace.py): `consent-protocol/api/routes/marketplace.py`

### API And Trust

- [FastAPI Service](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/server.py): `consent-protocol/server.py`
- [API Routes](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/api/routes): `consent-protocol/api/routes`
- [Identity And Auth](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/middleware.py): `consent-protocol/api/middleware.py`
- [Consent Protocol](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/consent_listener.py): `consent-protocol/api/consent_listener.py`

### Private Agents

- [One Agent](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/agents/one): `consent-protocol/hushh_mcp/agents/one`
- [Kai Finance](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/agents/kai/debate_engine.py): `consent-protocol/hushh_mcp/agents/kai/debate_engine.py`
- [Nav And KYC](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/agents): `consent-protocol/hushh_mcp/agents`
- [One Voice](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/one_voice): `consent-protocol/hushh_mcp/one_voice`
- [ADK And A2A](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/hushh_mcp/adk_bridge): `consent-protocol/hushh_mcp/adk_bridge`
- [MCP Surface](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/mcp_modules): `consent-protocol/mcp_modules`
- [Location And Wallet](https://github.com/hushh-labs/hushh-research/tree/main/consent-protocol/api/routes/one): `consent-protocol/api/routes/one`

### Knowledge And Connectors

- [Postgres Access](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/db/db_client.py): `consent-protocol/db/db_client.py`
- [PKM Storage API](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/pkm_routes_shared.py): `consent-protocol/api/routes/pkm_routes_shared.py`
- [PKM Service](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/personal_knowledge_model_service.py): `consent-protocol/hushh_mcp/services/personal_knowledge_model_service.py`
- [Drive Sharing](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/api/routes/drive_sharing.py): `consent-protocol/api/routes/drive_sharing.py`
- [Live Drive Queries](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/drive_live_query_service.py): `consent-protocol/hushh_mcp/services/drive_live_query_service.py`
- [Drive Ingestion](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/drive_ingestion_service.py): `consent-protocol/hushh_mcp/services/drive_ingestion_service.py`
- [Google Drive](https://github.com/hushh-labs/hushh-research/blob/main/consent-protocol/hushh_mcp/services/google_drive_adapter.py): `consent-protocol/hushh_mcp/services/google_drive_adapter.py`

### Other components

- **User**

## Connections

- User → Web And Mobile: uses (evidence: `README.md`)
- Web And Mobile → FastAPI Service: requests (evidence: `README.md`)
- FastAPI Service → API Routes: registers (evidence: `consent-protocol/server.py`)
- API Routes → Identity And Auth: protects (evidence: `consent-protocol/api/routes/pkm_routes_shared.py`)
- Identity And Auth → Consent Protocol: validates scopes (evidence: `consent-protocol/api/middleware.py`)
- Consent Protocol → Postgres Access: reads metadata (evidence: `consent-protocol/api/consent_listener.py`)
- API Routes → PKM Storage API: serves PKM
- PKM Storage API → PKM Service: delegates (evidence: `consent-protocol/api/routes/pkm_routes_shared.py`)
- API Routes → Drive Sharing: serves sharing (evidence: `consent-protocol/server.py`)
- Drive Sharing → Live Drive Queries: runs query (evidence: `consent-protocol/api/routes/drive_sharing.py`)
- Drive Ingestion → Google Drive: fetches content (evidence: `consent-protocol/hushh_mcp/services/drive_ingestion_service.py`)
- User → One Agent: converses (evidence: `README.md`)
- One Agent → Kai Finance: summons finance (evidence: `README.md`)
- One Agent → Nav And KYC: summons specialists (evidence: `README.md`)
- One Agent → One Voice: offers voice (evidence: `README.md`)
- One Agent → ADK And A2A: uses delegation (evidence: `README.md`)
- FastAPI Service → MCP Surface: exposes developer surface (evidence: `README.md`)
- User → Location And Wallet: uses location (evidence: `README.md`)
- User → Marketplace And RIA: uses workflows (evidence: `README.md`)
