# beep-boop-ship-it/jan-setu architecture

> Architecture diagram of the GitHub repository beep-boop-ship-it/jan-setu, 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/beep-boop-ship-it/jan-setu
- Repository: https://github.com/beep-boop-ship-it/jan-setu

## Overview

JAN SETU is a citizen-problem reporting and solver-coordination prototype: reports are submitted and tracked, checked for validity and duplication, analyzed and matched to expertise, then handled through proposals and review. The Go backend exposes the reporting, account, mentor, proposal and tracking APIs and persists application data; the Python AI service provides report analysis, duplicate detection and matching. The README also documents image/location reporting and an industry workflow. Frontend files are absent from the supplied tree, and sampled excerpts do not establish Go-to-AI wiring, so that connection is omitted.

Main entry points: [`backend/handlers.go`](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go) (API Handlers), [`ai/orchestrator.py`](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/orchestrator.py) (Workflow Orchestrator), [`ai/dedup/service.py`](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/service.py) (Duplicate Detection), [`ai/api/server.py`](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/api/server.py) (AI REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_go_server["Go HTTP Server<br/>[main.go]"]
  node_handlers["API Handlers<br/>[handlers.go]"]
end

subgraph group_ai_workflow["AI Analysis"]
  node_ai_api["AI REST API<br/>[server.py]"]
  node_orchestrator["Workflow Orchestrator<br/>[orchestrator.py]"]
  node_challenge["Report Analysis<br/>[analyzer.py]"]
  node_image_evidence["Image Evidence<br/>[analyzer.py]"]
  node_dedup_service["Duplicate Detection<br/>[service.py]"]
  node_matching["Expert Matching"]
  node_participant_matching["Participant Matching<br/>[participants.py]"]
end

subgraph group_ai_support["AI Support"]
  node_embeddings["Embedding Service<br/>[service.py]"]
  node_problem_retrieval["Problem Retrieval<br/>[retrieval.py]"]
  node_dedup_classifier["Relationship Classifier<br/>[classifier.py]"]
  node_organization_retrieval["Organization Retrieval<br/>[retrieval.py]"]
end

subgraph group_coordination["Solver Coordination"]
  node_proposals["Proposal Review<br/>[handlers.go]"]
  node_tracking["Report Tracking<br/>[handlers.go]"]
  node_solver_profiles["Solver Profiles<br/>[handlers.go]"]
end

subgraph group_external["External Services"]
  node_postgres[("PostgreSQL")]
  node_object_store[("Image Object Store")]
  node_providers["AI Providers"]
end

node_citizen(("Citizen"))
node_solver(("Solver / Mentor"))
node_industry(("Industry Expert"))

node_citizen -->|"submits report"| node_go_server
node_solver -->|"uses APIs"| node_go_server
node_industry -->|"uses APIs"| node_go_server
node_go_server -->|"dispatches requests"| node_handlers
node_handlers -->|"reads and writes"| node_postgres
node_handlers -->|"stores images"| node_object_store
node_handlers -->|"serves proposal actions"| node_proposals
node_handlers -->|"serves tracking"| node_tracking
node_handlers -->|"serves profiles"| node_solver_profiles
node_citizen -->|"requests analysis"| node_ai_api
node_ai_api -->|"runs workflow"| node_orchestrator
node_ai_api -->|"checks duplicates"| node_dedup_service
node_ai_api -->|"requests matches"| node_matching
node_orchestrator -->|"analyzes report"| node_challenge
node_orchestrator -->|"checks duplicates"| node_dedup_service
node_orchestrator -->|"matches expertise"| node_matching
node_orchestrator -->|"analyzes evidence"| node_image_evidence
node_orchestrator -->|"matches participants"| node_participant_matching
node_dedup_service -->|"embeds report"| node_embeddings
node_dedup_service -->|"retrieves candidates"| node_problem_retrieval
node_dedup_service -->|"classifies candidates"| node_dedup_classifier
node_matching -->|"embeds requirements"| node_embeddings
node_matching -->|"retrieves candidates"| node_organization_retrieval
node_challenge -.->|"requests generation"| node_providers
node_dedup_classifier -.->|"requests classification"| node_providers

click node_go_server "https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/main.go"
click node_handlers "https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go"
click node_ai_api "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/api/server.py"
click node_orchestrator "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/orchestrator.py"
click node_challenge "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/challenge/analyzer.py"
click node_image_evidence "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/image_evidence/analyzer.py"
click node_dedup_service "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/service.py"
click node_matching "https://github.com/beep-boop-ship-it/jan-setu/tree/main/ai/matching"
click node_participant_matching "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/matching/participants.py"
click node_embeddings "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/embeddings/service.py"
click node_problem_retrieval "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/retrieval.py"
click node_dedup_classifier "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/classifier.py"
click node_organization_retrieval "https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/matching/retrieval.py"
click node_providers "https://github.com/beep-boop-ship-it/jan-setu/tree/main/ai/providers"
click node_proposals "https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go"
click node_tracking "https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go"
click node_solver_profiles "https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go"

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_go_server,node_handlers toneBlue
class node_ai_api,node_orchestrator,node_challenge,node_image_evidence,node_dedup_service,node_matching,node_participant_matching toneAmber
class node_embeddings,node_problem_retrieval,node_dedup_classifier,node_organization_retrieval toneMint
class node_proposals,node_tracking,node_solver_profiles toneRose
class node_postgres,node_object_store,node_providers,node_citizen,node_solver,node_industry toneIndigo
```

## Components

### Backend API

- [Go HTTP Server](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/main.go): `backend/main.go`
- [API Handlers](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go): `backend/handlers.go`

### AI Analysis

- [AI REST API](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/api/server.py): `ai/api/server.py`
- [Workflow Orchestrator](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/orchestrator.py): `ai/orchestrator.py`
- [Report Analysis](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/challenge/analyzer.py): `ai/challenge/analyzer.py`
- [Image Evidence](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/image_evidence/analyzer.py): `ai/image_evidence/analyzer.py`
- [Duplicate Detection](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/service.py): `ai/dedup/service.py`
- [Expert Matching](https://github.com/beep-boop-ship-it/jan-setu/tree/main/ai/matching): `ai/matching`
- [Participant Matching](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/matching/participants.py): `ai/matching/participants.py`

### AI Support

- [Embedding Service](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/embeddings/service.py): `ai/embeddings/service.py`
- [Problem Retrieval](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/retrieval.py): `ai/dedup/retrieval.py`
- [Relationship Classifier](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/dedup/classifier.py): `ai/dedup/classifier.py`
- [Organization Retrieval](https://github.com/beep-boop-ship-it/jan-setu/blob/main/ai/matching/retrieval.py): `ai/matching/retrieval.py`

### Solver Coordination

- [Proposal Review](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go): `backend/handlers.go`
- [Report Tracking](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go): `backend/handlers.go`
- [Solver Profiles](https://github.com/beep-boop-ship-it/jan-setu/blob/main/backend/handlers.go): `backend/handlers.go`

### External Services

- **PostgreSQL**
- **Image Object Store**
- [AI Providers](https://github.com/beep-boop-ship-it/jan-setu/tree/main/ai/providers): `ai/providers`

### Other components

- **Citizen**
- **Solver / Mentor**
- **Industry Expert**

## Connections

- Citizen → Go HTTP Server: submits report
- Solver / Mentor → Go HTTP Server: uses APIs
- Industry Expert → Go HTTP Server: uses APIs
- Go HTTP Server → API Handlers: dispatches requests
- API Handlers → PostgreSQL: reads and writes
- API Handlers → Image Object Store: stores images
- API Handlers → Proposal Review: serves proposal actions
- API Handlers → Report Tracking: serves tracking
- API Handlers → Solver Profiles: serves profiles
- Citizen → AI REST API: requests analysis
- AI REST API → Workflow Orchestrator: runs workflow
- AI REST API → Duplicate Detection: checks duplicates
- AI REST API → Expert Matching: requests matches
- Workflow Orchestrator → Report Analysis: analyzes report
- Workflow Orchestrator → Duplicate Detection: checks duplicates
- Workflow Orchestrator → Expert Matching: matches expertise
- Workflow Orchestrator → Image Evidence: analyzes evidence
- Workflow Orchestrator → Participant Matching: matches participants
- Duplicate Detection → Embedding Service: embeds report
- Duplicate Detection → Problem Retrieval: retrieves candidates
- Duplicate Detection → Relationship Classifier: classifies candidates
- Expert Matching → Embedding Service: embeds requirements
- Expert Matching → Organization Retrieval: retrieves candidates
- Report Analysis → AI Providers: requests generation
- Relationship Classifier → AI Providers: requests classification