# preethamcodes/eksetu architecture

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

- Interactive diagram: https://gitdiagram.com/preethamcodes/eksetu
- Repository: https://github.com/preethamcodes/eksetu

## Overview

EKSetu is a consent- and policy-driven government verification gateway: a scholarship applicant initiates a request, the citizen reviews and grants or denies scoped consent, and authorized requests are evaluated and routed to departmental providers for verified results. The frontend also exposes citizen transparency and admin operations; backend audit, persistence, policy, security, and service-registry layers support those flows. Edges reflect README statements or SOURCE INDEX references and excerpts; unsampled controller and provider details are not expanded beyond documented behavior.

Main entry points: [`backend/src/services/interoperabilityService.ts`](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/interoperabilityService.ts) (Interoperability gateway), [`backend/src/routes/apiRoutes.ts`](https://github.com/preethamcodes/eksetu/blob/main/backend/src/routes/apiRoutes.ts) (API routes), [`frontend/src/services/api.ts`](https://github.com/preethamcodes/eksetu/blob/main/frontend/src/services/api.ts) (API client), [`backend/src/controllers/adminController.ts`](https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/adminController.ts) (Admin controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Citizen experience"]
  node_scholarship_ui["Scholarship flow"]
  node_transparency_ui["Transparency dashboard"]
  node_admin_ui["Admin operations"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_gateway["Gateway workflow"]
  node_api_routes["API routes<br/>[apiRoutes.ts]"]
  node_request_controller["Request controller"]
  node_consent_controller["Consent controller"]
  node_interoperability["Interoperability gateway"]
end

subgraph group_trust["Trust and governance"]
  node_consent["Consent management<br/>[consentService.ts]"]
  node_authorization["Service authorization"]
  node_policy["Policy evaluation<br/>[policyService.ts]"]
  node_policy_engine["Policy engine<br/>[policyEngine.ts]"]
end

subgraph group_providers["Department providers"]
  node_provider_registry["Provider registry"]
  node_education["Education provider"]
  node_revenue["Revenue provider<br/>[revenueProvider.ts]"]
  node_residence["Residence provider"]
end

subgraph group_operations["Operations and records"]
  node_service_registry["Service registry<br/>[serviceRegistry.ts]"]
  node_admin_controller["Admin controller<br/>[adminController.ts]"]
  node_audit["Audit and provenance<br/>[auditService.ts]"]
  node_database[("Request persistence<br/>[databaseService.ts]")]
  node_metrics["Operational metrics<br/>[metricsService.ts]"]
  node_security_events["Security events"]
  node_transparency_service["Transparency service"]
  node_citizen_controller["Citizen controller"]
end

node_citizen(("Citizen"))
node_scholarship["Scholarship portal"]
node_supabase[("Supabase")]

node_citizen -->|"submits request"| node_scholarship_ui
node_scholarship -->|"initiates verification"| node_api_client
node_scholarship_ui -->|"calls"| node_api_client
node_transparency_ui -->|"loads usage data"| node_api_client
node_admin_ui -->|"requests operations"| node_api_client
node_api_client -->|"sends API requests"| node_api_routes
node_api_routes -->|"routes requests"| node_request_controller
node_api_routes -->|"routes decisions"| node_consent_controller
node_api_routes -->|"routes citizen views"| node_citizen_controller
node_api_routes -->|"routes admin calls"| node_admin_controller
node_request_controller -->|"delegates verification"| node_interoperability
node_consent_controller -.->|"records decision"| node_consent
node_interoperability -->|"checks consent"| node_consent
node_interoperability -->|"checks service trust"| node_authorization
node_interoperability -->|"requests policy decision"| node_policy
node_policy -.->|"evaluates rules"| node_policy_engine
node_interoperability -->|"selects providers"| node_provider_registry
node_interoperability -->|"requests education proof"| node_education
node_interoperability -->|"requests income proof"| node_revenue
node_interoperability -->|"requests residence proof"| node_residence
node_interoperability -->|"checks service registry"| node_service_registry
node_interoperability -->|"records verification events"| node_audit
node_interoperability -->|"persists request data"| node_database
node_interoperability -->|"records metrics"| node_metrics
node_interoperability -->|"records security events"| node_security_events
node_admin_controller -->|"manages services"| node_service_registry
node_admin_controller -->|"reads metrics"| node_metrics
node_admin_controller -->|"reads security events"| node_security_events
node_citizen_controller -->|"loads citizen requests"| node_database
node_citizen_controller -->|"builds transparency view"| node_transparency_service
node_request_controller -->|"loads audit trail"| node_audit
node_audit -->|"stores and reads events"| node_database
node_database -->|"uses persistence"| node_supabase

click node_scholarship_ui "https://github.com/preethamcodes/eksetu/blob/main/frontend/src/pages/ScholarshipPage.tsx"
click node_transparency_ui "https://github.com/preethamcodes/eksetu/blob/main/frontend/src/components/CitizenTransparencyDashboard.tsx"
click node_admin_ui "https://github.com/preethamcodes/eksetu/blob/main/frontend/src/pages/AdminOperationsPage.tsx"
click node_api_client "https://github.com/preethamcodes/eksetu/blob/main/frontend/src/services/api.ts"
click node_api_routes "https://github.com/preethamcodes/eksetu/blob/main/backend/src/routes/apiRoutes.ts"
click node_request_controller "https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/requestController.ts"
click node_consent_controller "https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/consentController.ts"
click node_interoperability "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/interoperabilityService.ts"
click node_consent "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/consentService.ts"
click node_authorization "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/authorizationService.ts"
click node_policy "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/policyService.ts"
click node_policy_engine "https://github.com/preethamcodes/eksetu/blob/main/backend/src/policies/policyEngine.ts"
click node_provider_registry "https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/providerRegistry.ts"
click node_education "https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/educationProvider.ts"
click node_revenue "https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/revenueProvider.ts"
click node_residence "https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/residenceProvider.ts"
click node_service_registry "https://github.com/preethamcodes/eksetu/blob/main/backend/src/registry/serviceRegistry.ts"
click node_admin_controller "https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/adminController.ts"
click node_audit "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/auditService.ts"
click node_database "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/databaseService.ts"
click node_metrics "https://github.com/preethamcodes/eksetu/blob/main/backend/src/operations/metricsService.ts"
click node_security_events "https://github.com/preethamcodes/eksetu/blob/main/backend/src/operations/securityEventService.ts"
click node_transparency_service "https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/transparencyService.ts"
click node_citizen_controller "https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/citizenController.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_scholarship_ui,node_transparency_ui,node_admin_ui,node_api_client toneBlue
class node_api_routes,node_request_controller,node_consent_controller,node_interoperability,node_supabase toneAmber
class node_consent,node_authorization,node_policy,node_policy_engine toneMint
class node_provider_registry,node_education,node_revenue,node_residence toneRose
class node_service_registry,node_admin_controller,node_audit,node_database,node_metrics,node_security_events,node_transparency_service,node_citizen_controller,node_citizen,node_scholarship toneIndigo
```

## Components

### Citizen experience

- [Scholarship flow](https://github.com/preethamcodes/eksetu/blob/main/frontend/src/pages/ScholarshipPage.tsx): `frontend/src/pages/ScholarshipPage.tsx`
- [Transparency dashboard](https://github.com/preethamcodes/eksetu/blob/main/frontend/src/components/CitizenTransparencyDashboard.tsx): `frontend/src/components/CitizenTransparencyDashboard.tsx`
- [Admin operations](https://github.com/preethamcodes/eksetu/blob/main/frontend/src/pages/AdminOperationsPage.tsx): `frontend/src/pages/AdminOperationsPage.tsx`
- [API client](https://github.com/preethamcodes/eksetu/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Gateway workflow

- [API routes](https://github.com/preethamcodes/eksetu/blob/main/backend/src/routes/apiRoutes.ts): `backend/src/routes/apiRoutes.ts`
- [Request controller](https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/requestController.ts): `backend/src/controllers/requestController.ts`
- [Consent controller](https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/consentController.ts): `backend/src/controllers/consentController.ts`
- [Interoperability gateway](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/interoperabilityService.ts): `backend/src/services/interoperabilityService.ts`

### Trust and governance

- [Consent management](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/consentService.ts): `backend/src/services/consentService.ts`
- [Service authorization](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/authorizationService.ts): `backend/src/services/authorizationService.ts`
- [Policy evaluation](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/policyService.ts): `backend/src/services/policyService.ts`
- [Policy engine](https://github.com/preethamcodes/eksetu/blob/main/backend/src/policies/policyEngine.ts): `backend/src/policies/policyEngine.ts`

### Department providers

- [Provider registry](https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/providerRegistry.ts): `backend/src/providers/providerRegistry.ts`
- [Education provider](https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/educationProvider.ts): `backend/src/providers/educationProvider.ts`
- [Revenue provider](https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/revenueProvider.ts): `backend/src/providers/revenueProvider.ts`
- [Residence provider](https://github.com/preethamcodes/eksetu/blob/main/backend/src/providers/residenceProvider.ts): `backend/src/providers/residenceProvider.ts`

### Operations and records

- [Service registry](https://github.com/preethamcodes/eksetu/blob/main/backend/src/registry/serviceRegistry.ts): `backend/src/registry/serviceRegistry.ts`
- [Admin controller](https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/adminController.ts): `backend/src/controllers/adminController.ts`
- [Audit and provenance](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/auditService.ts): `backend/src/services/auditService.ts`
- [Request persistence](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/databaseService.ts): `backend/src/services/databaseService.ts`
- [Operational metrics](https://github.com/preethamcodes/eksetu/blob/main/backend/src/operations/metricsService.ts): `backend/src/operations/metricsService.ts`
- [Security events](https://github.com/preethamcodes/eksetu/blob/main/backend/src/operations/securityEventService.ts): `backend/src/operations/securityEventService.ts`
- [Transparency service](https://github.com/preethamcodes/eksetu/blob/main/backend/src/services/transparencyService.ts): `backend/src/services/transparencyService.ts`
- [Citizen controller](https://github.com/preethamcodes/eksetu/blob/main/backend/src/controllers/citizenController.ts): `backend/src/controllers/citizenController.ts`

### Other components

- **Citizen**
- **Scholarship portal**
- **Supabase**

## Connections

- Citizen → Scholarship flow: submits request (evidence: `README.md`)
- Scholarship portal → API client: initiates verification (evidence: `README.md`)
- Scholarship flow → API client: calls (evidence: `frontend/src/pages/ScholarshipPage.tsx`)
- Transparency dashboard → API client: loads usage data (evidence: `frontend/src/components/CitizenTransparencyDashboard.tsx`)
- Admin operations → API client: requests operations (evidence: `frontend/src/pages/AdminOperationsPage.tsx`)
- API client → API routes: sends API requests (evidence: `README.md`)
- API routes → Request controller: routes requests (evidence: `backend/src/routes/apiRoutes.ts`)
- API routes → Consent controller: routes decisions (evidence: `backend/src/routes/apiRoutes.ts`)
- API routes → Citizen controller: routes citizen views (evidence: `backend/src/routes/apiRoutes.ts`)
- API routes → Admin controller: routes admin calls (evidence: `backend/src/routes/apiRoutes.ts`)
- Request controller → Interoperability gateway: delegates verification (evidence: `backend/src/controllers/requestController.ts`)
- Consent controller → Consent management: records decision
- Interoperability gateway → Consent management: checks consent (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Service authorization: checks service trust (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Policy evaluation: requests policy decision (evidence: `backend/src/services/interoperabilityService.ts`)
- Policy evaluation → Policy engine: evaluates rules
- Interoperability gateway → Provider registry: selects providers (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Education provider: requests education proof (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Revenue provider: requests income proof (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Residence provider: requests residence proof (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Service registry: checks service registry (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Audit and provenance: records verification events (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Request persistence: persists request data (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Operational metrics: records metrics (evidence: `backend/src/services/interoperabilityService.ts`)
- Interoperability gateway → Security events: records security events (evidence: `backend/src/services/interoperabilityService.ts`)
- Admin controller → Service registry: manages services (evidence: `backend/src/controllers/adminController.ts`)
- Admin controller → Operational metrics: reads metrics (evidence: `backend/src/controllers/adminController.ts`)
- Admin controller → Security events: reads security events (evidence: `backend/src/controllers/adminController.ts`)
- Citizen controller → Request persistence: loads citizen requests (evidence: `backend/src/controllers/citizenController.ts`)
- Citizen controller → Transparency service: builds transparency view (evidence: `backend/src/controllers/citizenController.ts`)
- Request controller → Audit and provenance: loads audit trail (evidence: `backend/src/controllers/requestController.ts`)
- Audit and provenance → Request persistence: stores and reads events (evidence: `backend/src/services/auditService.ts`)
- Request persistence → Supabase: uses persistence (evidence: `backend/src/services/databaseService.ts`)