# skygod07/tale-s_of_goa architecture

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

- Interactive diagram: https://gitdiagram.com/skygod07/tale-s_of_goa
- Repository: https://github.com/skygod07/tale-s_of_goa

## Overview

Tales of Goa is a face-identification and social-post verification product, available through a web UI and a CLI. Its main workflow accepts a face image, searches for public social content, verifies candidate faces, then commits a hash and reads back the on-chain proof. The backend also supports direct face operations, an enrolled identity gallery, teaching, and feedback/calibration. The graph includes documented capabilities whose implementation was not sampled; edges are limited to shown calls, imports, endpoint mappings, or README statements.

Main entry points: [`backend/app/routes/social.py`](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/social.py) (Social endpoints), [`backend/app/services/social_search.py`](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/social_search.py) (Social pipeline), [`backend/app/services/face_processor.py`](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/face_processor.py) (Face processing), [`backend/app/routes/face.py`](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/face.py) (Face endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_web["Web application<br/>[page.tsx]"]
  node_pipeline_ui["Discovery workflow UI"]
  node_pipeline_stages["Progress stages<br/>[PipelineStages.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_face_routes["Face endpoints<br/>[face.py]"]
  node_social_routes["Social endpoints<br/>[social.py]"]
  node_verification_routes["Verification endpoints<br/>[verification.py]"]
  node_face_schema["Face API schemas<br/>[face.py]"]
  node_cli["Pipeline CLI<br/>[run_pipeline.py]"]
end

subgraph group_identity["Face identity"]
  node_face_processor["Face processing<br/>[face_processor.py]"]
  node_gallery[("Identity gallery<br/>[gallery.py]")]
  node_naming["Identity naming<br/>[naming.py]"]
end

subgraph group_discovery["Discovery and learning"]
  node_face_search["Face-driven search<br/>[face_search.py]"]
  node_social_search["Social pipeline<br/>[social_search.py]"]
  node_teach["Identity teaching<br/>[teach.py]"]
  node_feedback["Feedback calibration<br/>[feedback.py]"]
end

subgraph group_proof["Blockchain proof"]
  node_hashing["Record hashing<br/>[hashing.py]"]
  node_blockchain_service["Chain integration<br/>[blockchain.py]"]
end

node_user(("Operator"))
node_evm[("EVM network")]

node_user -->|"uses"| node_web
node_web -->|"requests"| node_api_client
node_web -->|"renders"| node_pipeline_ui
node_pipeline_ui -->|"runs search"| node_api_client
node_pipeline_ui -->|"renders progress"| node_pipeline_stages
node_api_client -->|"calls face API"| node_face_routes
node_api_client -->|"calls search API"| node_social_routes
node_api_client -->|"queries proof"| node_verification_routes
node_fastapi -->|"registers"| node_face_routes
node_fastapi -->|"registers"| node_social_routes
node_fastapi -->|"registers"| node_verification_routes
node_face_routes -->|"processes faces"| node_face_processor
node_face_routes -->|"hashes records"| node_hashing
node_face_routes -->|"records proof"| node_blockchain_service
node_face_routes -->|"uses schemas"| node_face_schema
node_verification_routes -->|"queries chain"| node_blockchain_service
node_verification_routes -->|"uses schemas"| node_face_schema
node_social_routes -->|"runs pipeline"| node_social_search
node_social_routes -->|"uses search"| node_face_search
node_social_routes -->|"processes faces"| node_face_processor
node_social_routes -->|"uses gallery"| node_gallery
node_social_routes -->|"teaches identity"| node_teach
node_social_routes -->|"records feedback"| node_feedback
node_face_search -->|"uses embeddings"| node_face_processor
node_face_search -->|"uses names"| node_naming
node_face_search -->|"uses calibration"| node_feedback
node_social_search -->|"uses discovery"| node_face_search
node_social_search -->|"verifies faces"| node_face_processor
node_social_search -->|"uses gallery"| node_gallery
node_social_search -->|"hashes record"| node_hashing
node_social_search -->|"commits proof"| node_blockchain_service
node_teach -->|"encodes faces"| node_face_processor
node_teach -->|"enrolls identity"| node_gallery
node_teach -->|"resolves name"| node_naming
node_feedback -->|"evaluates faces"| node_face_processor
node_feedback -->|"hashes feedback"| node_hashing
node_feedback -->|"records evidence"| node_blockchain_service
node_blockchain_service -->|"submits and reads"| node_evm
node_user -->|"runs pipeline"| node_cli
node_cli -->|"runs discovery"| node_social_search
node_cli -->|"encodes input"| node_face_processor
node_cli -->|"searches faces"| node_face_search
node_cli -->|"commits proof"| node_blockchain_service

click node_web "https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/app/page.tsx"
click node_pipeline_ui "https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/components/SocialDiscoveryPipeline.tsx"
click node_pipeline_stages "https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/components/PipelineStages.tsx"
click node_api_client "https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/services/api.ts"
click node_fastapi "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/main.py"
click node_face_routes "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/face.py"
click node_social_routes "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/social.py"
click node_verification_routes "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/verification.py"
click node_face_schema "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/schemas/face.py"
click node_face_processor "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/face_processor.py"
click node_face_search "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/face_search.py"
click node_social_search "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/social_search.py"
click node_gallery "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/gallery.py"
click node_teach "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/teach.py"
click node_naming "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/naming.py"
click node_feedback "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/feedback.py"
click node_hashing "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/hashing.py"
click node_blockchain_service "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/blockchain.py"
click node_cli "https://github.com/skygod07/tale-s_of_goa/blob/main/backend/run_pipeline.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_pipeline_ui,node_pipeline_stages,node_api_client toneBlue
class node_fastapi,node_face_routes,node_social_routes,node_verification_routes,node_face_schema,node_cli,node_evm toneAmber
class node_face_processor,node_gallery,node_naming toneMint
class node_face_search,node_social_search,node_teach,node_feedback toneRose
class node_hashing,node_blockchain_service,node_user toneIndigo
```

## Components

### Web interface

- [Web application](https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Discovery workflow UI](https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/components/SocialDiscoveryPipeline.tsx): `frontend/src/components/SocialDiscoveryPipeline.tsx`
- [Progress stages](https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/components/PipelineStages.tsx): `frontend/src/components/PipelineStages.tsx`
- [API client](https://github.com/skygod07/tale-s_of_goa/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and orchestration

- [FastAPI app](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/main.py): `backend/app/main.py`
- [Face endpoints](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/face.py): `backend/app/routes/face.py`
- [Social endpoints](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/social.py): `backend/app/routes/social.py`
- [Verification endpoints](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/routes/verification.py): `backend/app/routes/verification.py`
- [Face API schemas](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/schemas/face.py): `backend/app/schemas/face.py`
- [Pipeline CLI](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/run_pipeline.py): `backend/run_pipeline.py`

### Face identity

- [Face processing](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/face_processor.py): `backend/app/services/face_processor.py`
- [Identity gallery](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/gallery.py): `backend/app/services/gallery.py`
- [Identity naming](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/naming.py): `backend/app/services/naming.py`

### Discovery and learning

- [Face-driven search](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/face_search.py): `backend/app/services/face_search.py`
- [Social pipeline](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/social_search.py): `backend/app/services/social_search.py`
- [Identity teaching](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/teach.py): `backend/app/services/teach.py`
- [Feedback calibration](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/feedback.py): `backend/app/services/feedback.py`

### Blockchain proof

- [Record hashing](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/hashing.py): `backend/app/services/hashing.py`
- [Chain integration](https://github.com/skygod07/tale-s_of_goa/blob/main/backend/app/services/blockchain.py): `backend/app/services/blockchain.py`

### Other components

- **Operator**
- **EVM network**

## Connections

- Operator → Web application: uses (evidence: `README.md`)
- Web application → API client: requests (evidence: `frontend/src/app/page.tsx`)
- Web application → Discovery workflow UI: renders (evidence: `frontend/src/app/page.tsx`)
- Discovery workflow UI → API client: runs search (evidence: `frontend/src/components/SocialDiscoveryPipeline.tsx`)
- Discovery workflow UI → Progress stages: renders progress (evidence: `frontend/src/components/SocialDiscoveryPipeline.tsx`)
- API client → Face endpoints: calls face API (evidence: `frontend/src/services/api.ts`)
- API client → Social endpoints: calls search API (evidence: `frontend/src/services/api.ts`)
- API client → Verification endpoints: queries proof (evidence: `frontend/src/services/api.ts`)
- FastAPI app → Face endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Social endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Verification endpoints: registers (evidence: `backend/app/main.py`)
- Face endpoints → Face processing: processes faces (evidence: `backend/app/routes/face.py`)
- Face endpoints → Record hashing: hashes records (evidence: `backend/app/routes/face.py`)
- Face endpoints → Chain integration: records proof (evidence: `backend/app/routes/face.py`)
- Face endpoints → Face API schemas: uses schemas (evidence: `backend/app/routes/face.py`)
- Verification endpoints → Chain integration: queries chain (evidence: `backend/app/routes/verification.py`)
- Verification endpoints → Face API schemas: uses schemas (evidence: `backend/app/routes/verification.py`)
- Social endpoints → Social pipeline: runs pipeline (evidence: `backend/app/routes/social.py`)
- Social endpoints → Face-driven search: uses search (evidence: `backend/app/routes/social.py`)
- Social endpoints → Face processing: processes faces (evidence: `backend/app/routes/social.py`)
- Social endpoints → Identity gallery: uses gallery (evidence: `backend/app/routes/social.py`)
- Social endpoints → Identity teaching: teaches identity (evidence: `backend/app/routes/social.py`)
- Social endpoints → Feedback calibration: records feedback (evidence: `backend/app/routes/social.py`)
- Face-driven search → Face processing: uses embeddings (evidence: `backend/app/services/face_search.py`)
- Face-driven search → Identity naming: uses names (evidence: `backend/app/services/face_search.py`)
- Face-driven search → Feedback calibration: uses calibration (evidence: `backend/app/services/face_search.py`)
- Social pipeline → Face-driven search: uses discovery (evidence: `backend/app/services/social_search.py`)
- Social pipeline → Face processing: verifies faces (evidence: `backend/app/services/social_search.py`)
- Social pipeline → Identity gallery: uses gallery (evidence: `backend/app/services/social_search.py`)
- Social pipeline → Record hashing: hashes record (evidence: `backend/app/services/social_search.py`)
- Social pipeline → Chain integration: commits proof (evidence: `backend/app/services/social_search.py`)
- Identity teaching → Face processing: encodes faces (evidence: `backend/app/services/teach.py`)
- Identity teaching → Identity gallery: enrolls identity (evidence: `backend/app/services/teach.py`)
- Identity teaching → Identity naming: resolves name (evidence: `backend/app/services/teach.py`)
- Feedback calibration → Face processing: evaluates faces (evidence: `backend/app/services/feedback.py`)
- Feedback calibration → Record hashing: hashes feedback (evidence: `backend/app/services/feedback.py`)
- Feedback calibration → Chain integration: records evidence (evidence: `backend/app/services/feedback.py`)
- Chain integration → EVM network: submits and reads (evidence: `README.md`)
- Operator → Pipeline CLI: runs pipeline (evidence: `README.md`)
- Pipeline CLI → Social pipeline: runs discovery (evidence: `backend/run_pipeline.py`)
- Pipeline CLI → Face processing: encodes input (evidence: `backend/run_pipeline.py`)
- Pipeline CLI → Face-driven search: searches faces (evidence: `backend/run_pipeline.py`)
- Pipeline CLI → Chain integration: commits proof (evidence: `backend/run_pipeline.py`)
