# anburocky3/indian-colleges-data architecture

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

- Interactive diagram: https://gitdiagram.com/anburocky3/indian-colleges-data
- Repository: https://github.com/anburocky3/indian-colleges-data

## Overview

This repository publishes AICTE-sourced Indian institution data through a Next.js API and a small endpoint-discovery page. The main workflow is a caller requesting an institution list, state snapshot, search result, or institution’s programmes; handlers read local JSON snapshots, with the main list optionally fetching AICTE live. The documented ingestion and enrichment scripts refresh snapshots and add programme details. Source excerpts establish the API’s file reads and live fetch; some other subsystem links are documented in the README rather than verified in unsampled code.

Main entry points: [`app/api/institutions/route.ts`](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/route.ts) (Institution list), [`data/states`](https://github.com/anburocky3/indian-colleges-data/tree/main/data/states) (State snapshots), [`scripts/download-all-states.ts`](https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/download-all-states.ts) (State downloader), [`scripts/merge-from-states.ts`](https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/merge-from-states.ts) (Programme enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Web interface"]
  node_home["Endpoint guide<br/>[page.tsx]"]
end

subgraph group_api["Institution API"]
  node_all["Institution list<br/>[route.ts]"]
  node_search["Institution search<br/>[route.ts]"]
  node_states["State directory<br/>[route.ts]"]
  node_state["State institutions<br/>[route.ts]"]
  node_programmes["Institution programmes<br/>[route.ts]"]
end

subgraph group_dataset["Data snapshots"]
  node_aggregate["All-institutions snapshot<br/>[institutions.json]"]
  node_statefiles["State snapshots"]
  node_enriched["Programmes snapshot"]
  node_metadata["Snapshot metadata"]
end

subgraph group_refresh["Data refresh"]
  node_downloader["State downloader"]
  node_enricher["Programme enrichment"]
end

node_visitor(("API consumer"))
node_aicte["AICTE service"]

node_visitor -->|"opens"| node_home
node_visitor -->|"requests"| node_all
node_visitor -->|"searches"| node_search
node_visitor -->|"lists states"| node_states
node_visitor -->|"requests state"| node_state
node_visitor -->|"requests courses"| node_programmes
node_home -->|"links to"| node_all
node_all -->|"reads offline"| node_aggregate
node_all -->|"reads metadata"| node_metadata
node_all -->|"fetches online"| node_aicte
node_states -->|"imports state list"| node_all
node_state -->|"imports CORS helper"| node_all
node_state -->|"reads snapshot"| node_statefiles
node_programmes -->|"reads snapshot"| node_statefiles
node_search -->|"reads state data"| node_statefiles
node_search -->|"reads fallback"| node_aggregate
node_downloader -->|"downloads data"| node_aicte
node_downloader -->|"writes snapshots"| node_statefiles
node_downloader -->|"writes merged data"| node_aggregate
node_downloader -->|"writes metadata"| node_metadata
node_enricher -->|"reads and updates"| node_statefiles
node_enricher -->|"fetches programmes"| node_aicte
node_enricher -->|"writes combined data"| node_enriched

click node_home "https://github.com/anburocky3/indian-colleges-data/blob/main/app/page.tsx"
click node_all "https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/route.ts"
click node_search "https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/search/route.ts"
click node_states "https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/route.ts"
click node_state "https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/%5Bstate%5D/route.ts"
click node_programmes "https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/%5Bstate%5D/%5Baicteid%5D/route.ts"
click node_aggregate "https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions.json"
click node_statefiles "https://github.com/anburocky3/indian-colleges-data/tree/main/data/states"
click node_enriched "https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions-with-programmes.json"
click node_metadata "https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions.meta.json"
click node_downloader "https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/download-all-states.ts"
click node_enricher "https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/merge-from-states.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_home toneBlue
class node_all,node_search,node_states,node_state,node_programmes toneAmber
class node_aggregate,node_statefiles,node_enriched,node_metadata,node_visitor toneMint
class node_downloader,node_enricher toneRose
class node_aicte toneIndigo
```

## Components

### Web interface

- [Endpoint guide](https://github.com/anburocky3/indian-colleges-data/blob/main/app/page.tsx): `app/page.tsx`

### Institution API

- [Institution list](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/route.ts): `app/api/institutions/route.ts`
- [Institution search](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/search/route.ts): `app/api/institutions/search/route.ts`
- [State directory](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/route.ts): `app/api/institutions/states/route.ts`
- [State institutions](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/%5Bstate%5D/route.ts): `app/api/institutions/states/[state]/route.ts`
- [Institution programmes](https://github.com/anburocky3/indian-colleges-data/blob/main/app/api/institutions/states/%5Bstate%5D/%5Baicteid%5D/route.ts): `app/api/institutions/states/[state]/[aicteid]/route.ts`

### Data snapshots

- [All-institutions snapshot](https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions.json): `data/institutions.json`
- [State snapshots](https://github.com/anburocky3/indian-colleges-data/tree/main/data/states): `data/states`
- [Programmes snapshot](https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions-with-programmes.json): `data/institutions-with-programmes.json`
- [Snapshot metadata](https://github.com/anburocky3/indian-colleges-data/blob/main/data/institutions.meta.json): `data/institutions.meta.json`

### Data refresh

- [State downloader](https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/download-all-states.ts): `scripts/download-all-states.ts`
- [Programme enrichment](https://github.com/anburocky3/indian-colleges-data/blob/main/scripts/merge-from-states.ts): `scripts/merge-from-states.ts`

### Other components

- **API consumer**
- **AICTE service**

## Connections

- API consumer → Endpoint guide: opens (evidence: `README.md`)
- API consumer → Institution list: requests (evidence: `README.md`)
- API consumer → Institution search: searches (evidence: `README.md`)
- API consumer → State directory: lists states (evidence: `README.md`)
- API consumer → State institutions: requests state (evidence: `README.md`)
- API consumer → Institution programmes: requests courses (evidence: `README.md`)
- Endpoint guide → Institution list: links to (evidence: `app/page.tsx`)
- Institution list → All-institutions snapshot: reads offline (evidence: `app/api/institutions/route.ts`)
- Institution list → Snapshot metadata: reads metadata (evidence: `app/api/institutions/route.ts`)
- Institution list → AICTE service: fetches online (evidence: `app/api/institutions/route.ts`)
- State directory → Institution list: imports state list (evidence: `app/api/institutions/states/route.ts`)
- State institutions → Institution list: imports CORS helper (evidence: `app/api/institutions/states/[state]/route.ts`)
- State institutions → State snapshots: reads snapshot (evidence: `app/api/institutions/states/[state]/route.ts`)
- Institution programmes → State snapshots: reads snapshot (evidence: `app/api/institutions/states/[state]/[aicteid]/route.ts`)
- Institution search → State snapshots: reads state data (evidence: `app/api/institutions/search/route.ts`)
- Institution search → All-institutions snapshot: reads fallback (evidence: `app/api/institutions/search/route.ts`)
- State downloader → AICTE service: downloads data (evidence: `scripts/download-all-states.ts`)
- State downloader → State snapshots: writes snapshots (evidence: `scripts/download-all-states.ts`)
- State downloader → All-institutions snapshot: writes merged data (evidence: `scripts/download-all-states.ts`)
- State downloader → Snapshot metadata: writes metadata (evidence: `scripts/download-all-states.ts`)
- Programme enrichment → State snapshots: reads and updates (evidence: `scripts/merge-from-states.ts`)
- Programme enrichment → AICTE service: fetches programmes (evidence: `scripts/merge-from-states.ts`)
- Programme enrichment → Programmes snapshot: writes combined data (evidence: `scripts/merge-from-states.ts`)
