# samir-deshmukh/sam architecture

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

- Interactive diagram: https://gitdiagram.com/samir-deshmukh/sam
- Repository: https://github.com/samir-deshmukh/sam

## Overview

CET CAP is a college-admission decision-support application: candidates search colleges by city, percentage and course, then inspect category-specific cutoff and seat details. Administrators also manage data imports, review and publish validated results, and resolve college websites. The graph separates the public lookup path from the administrative data workflow. Source excerpts establish the public search calls and several import relationships; the README is empty, so unsampled capability links are limited to relationships listed in the SOURCE INDEX.

Main entry points: [`cet/backend/main.py`](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/main.py) (Admin and API server), [`cet/backend/admin/db.py`](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/db.py) (Admin database layer), [`cet/backend/admin/processing.py`](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/processing.py) (Extraction and validation), [`cet/app/Home.py`](https://github.com/samir-deshmukh/sam/blob/main/cet/app/Home.py) (Search and details)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Candidate portal"]
  node_home["Search and details<br/>[Home.py]"]
  node_queries["Cutoff and seat queries<br/>[queries.py]"]
  node_search["Search aggregation<br/>[search.py]"]
end

subgraph group_admin["Admin operations"]
  node_server["Admin and API server<br/>[main.py]"]
  node_api["Public API<br/>[api.py]"]
  node_adminui["Admin interface<br/>[admin_ui.py]"]
  node_adminstate["Import state<br/>[state.py]"]
  node_resolver["College website resolver<br/>[resolver.py]"]
end

subgraph group_imports["Data imports"]
  node_pipeline["PDF identification<br/>[pipeline.py]"]
  node_processing["Extraction and validation<br/>[processing.py]"]
  node_publishing["Import publishing<br/>[publishing.py]"]
  node_cutoffingest["Cutoff ingestion<br/>[ingest.py]"]
  node_seattingest["Seat ingestion<br/>[ingest_seats.py]"]
  node_cutoffvalidate["Cutoff validation<br/>[validate_data.py]"]
  node_seatvalidate["Seat validation<br/>[validate_seats.py]"]
end

subgraph group_platform["Data platform"]
  node_publicdb["PostgreSQL access<br/>[db.py]"]
  node_database[("PostgreSQL database")]
  node_admindb["Admin database layer<br/>[db.py]"]
  node_migrations["Schema migrations<br/>[migrations.py]"]
  node_bootstrap["Database bootstrap<br/>[db_bootstrap.py]"]
end

node_candidate(("Candidate"))
node_admin(("Administrator"))

node_candidate -->|"searches"| node_home
node_home -->|"opens connection"| node_publicdb
node_home -->|"fetches results"| node_queries
node_home -->|"filters results"| node_search
node_queries -->|"reads"| node_database
node_publicdb -->|"connects"| node_database
node_admin -->|"manages data"| node_server
node_server -->|"serves interface"| node_adminui
node_adminui -->|"calls endpoints"| node_server
node_server -->|"routes API"| node_api
node_server -->|"invokes identification"| node_pipeline
node_server -->|"invokes processing"| node_processing
node_server -->|"invokes publishing"| node_publishing
node_server -->|"invokes resolver"| node_resolver
node_server -->|"runs migrations"| node_migrations
node_server -->|"uses statuses"| node_adminstate
node_pipeline -->|"records events"| node_admindb
node_pipeline -->|"sets status"| node_adminstate
node_processing -->|"stores staging data"| node_admindb
node_processing -->|"validates cutoffs"| node_cutoffvalidate
node_processing -->|"validates seats"| node_seatvalidate
node_processing -->|"uses seat loader"| node_seattingest
node_cutoffingest -->|"initializes schema"| node_bootstrap
node_cutoffingest -->|"uses validation"| node_cutoffvalidate
node_seattingest -->|"initializes schema"| node_bootstrap
node_seattingest -->|"uses validation"| node_seatvalidate
node_admindb -->|"reads and writes"| node_database
node_migrations -->|"updates schema"| node_admindb
node_publishing -.->|"commits imports"| node_admindb
node_resolver -->|"updates records"| node_admindb

click node_home "https://github.com/samir-deshmukh/sam/blob/main/cet/app/Home.py"
click node_queries "https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/queries.py"
click node_search "https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/search.py"
click node_publicdb "https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/db.py"
click node_server "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/main.py"
click node_api "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/api.py"
click node_adminui "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin_ui.py"
click node_adminstate "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/state.py"
click node_admindb "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/db.py"
click node_migrations "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/migrations.py"
click node_pipeline "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/pipeline.py"
click node_processing "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/processing.py"
click node_publishing "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/publishing.py"
click node_resolver "https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/resolver.py"
click node_cutoffingest "https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/ingest.py"
click node_seattingest "https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/ingest_seats.py"
click node_bootstrap "https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/db_bootstrap.py"
click node_cutoffvalidate "https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/validate_data.py"
click node_seatvalidate "https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/validate_seats.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_home,node_queries,node_search toneBlue
class node_server,node_api,node_adminui,node_adminstate,node_resolver toneAmber
class node_pipeline,node_processing,node_publishing,node_cutoffingest,node_seattingest,node_cutoffvalidate,node_seatvalidate toneMint
class node_publicdb,node_database,node_admindb,node_migrations,node_bootstrap toneRose
class node_candidate,node_admin toneIndigo
```

## Components

### Candidate portal

- [Search and details](https://github.com/samir-deshmukh/sam/blob/main/cet/app/Home.py): `cet/app/Home.py`
- [Cutoff and seat queries](https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/queries.py): `cet/src/cet_cap/queries.py`
- [Search aggregation](https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/search.py): `cet/src/cet_cap/search.py`

### Admin operations

- [Admin and API server](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/main.py): `cet/backend/main.py`
- [Public API](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/api.py): `cet/backend/api.py`
- [Admin interface](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin_ui.py): `cet/backend/admin_ui.py`
- [Import state](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/state.py): `cet/backend/admin/state.py`
- [College website resolver](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/resolver.py): `cet/backend/admin/resolver.py`

### Data imports

- [PDF identification](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/pipeline.py): `cet/backend/admin/pipeline.py`
- [Extraction and validation](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/processing.py): `cet/backend/admin/processing.py`
- [Import publishing](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/publishing.py): `cet/backend/admin/publishing.py`
- [Cutoff ingestion](https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/ingest.py): `cet/scripts/ingest.py`
- [Seat ingestion](https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/ingest_seats.py): `cet/scripts/ingest_seats.py`
- [Cutoff validation](https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/validate_data.py): `cet/scripts/validate_data.py`
- [Seat validation](https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/validate_seats.py): `cet/scripts/validate_seats.py`

### Data platform

- [PostgreSQL access](https://github.com/samir-deshmukh/sam/blob/main/cet/src/cet_cap/db.py): `cet/src/cet_cap/db.py`
- **PostgreSQL database**
- [Admin database layer](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/db.py): `cet/backend/admin/db.py`
- [Schema migrations](https://github.com/samir-deshmukh/sam/blob/main/cet/backend/admin/migrations.py): `cet/backend/admin/migrations.py`
- [Database bootstrap](https://github.com/samir-deshmukh/sam/blob/main/cet/scripts/db_bootstrap.py): `cet/scripts/db_bootstrap.py`

### Other components

- **Candidate**
- **Administrator**

## Connections

- Candidate → Search and details: searches (evidence: `cet/app/Home.py`)
- Search and details → PostgreSQL access: opens connection (evidence: `cet/app/Home.py`)
- Search and details → Cutoff and seat queries: fetches results (evidence: `cet/app/Home.py`)
- Search and details → Search aggregation: filters results (evidence: `cet/app/Home.py`)
- Cutoff and seat queries → PostgreSQL database: reads (evidence: `cet/src/cet_cap/queries.py`)
- PostgreSQL access → PostgreSQL database: connects (evidence: `cet/src/cet_cap/db.py`)
- Administrator → Admin and API server: manages data (evidence: `cet/backend/main.py`)
- Admin and API server → Admin interface: serves interface (evidence: `cet/backend/main.py`)
- Admin interface → Admin and API server: calls endpoints (evidence: `cet/backend/admin_ui.py`)
- Admin and API server → Public API: routes API (evidence: `cet/backend/main.py`)
- Admin and API server → PDF identification: invokes identification (evidence: `cet/backend/main.py`)
- Admin and API server → Extraction and validation: invokes processing (evidence: `cet/backend/main.py`)
- Admin and API server → Import publishing: invokes publishing (evidence: `cet/backend/main.py`)
- Admin and API server → College website resolver: invokes resolver (evidence: `cet/backend/main.py`)
- Admin and API server → Schema migrations: runs migrations (evidence: `cet/backend/main.py`)
- Admin and API server → Import state: uses statuses (evidence: `cet/backend/main.py`)
- PDF identification → Admin database layer: records events (evidence: `cet/backend/admin/pipeline.py`)
- PDF identification → Import state: sets status (evidence: `cet/backend/admin/pipeline.py`)
- Extraction and validation → Admin database layer: stores staging data (evidence: `cet/backend/admin/processing.py`)
- Extraction and validation → Cutoff validation: validates cutoffs (evidence: `cet/backend/admin/processing.py`)
- Extraction and validation → Seat validation: validates seats (evidence: `cet/backend/admin/processing.py`)
- Extraction and validation → Seat ingestion: uses seat loader (evidence: `cet/backend/admin/processing.py`)
- Cutoff ingestion → Database bootstrap: initializes schema (evidence: `cet/scripts/ingest.py`)
- Cutoff ingestion → Cutoff validation: uses validation (evidence: `cet/scripts/ingest.py`)
- Seat ingestion → Database bootstrap: initializes schema (evidence: `cet/scripts/ingest_seats.py`)
- Seat ingestion → Seat validation: uses validation (evidence: `cet/scripts/ingest_seats.py`)
- Admin database layer → PostgreSQL database: reads and writes (evidence: `cet/backend/admin/db.py`)
- Schema migrations → Admin database layer: updates schema (evidence: `cet/backend/admin/migrations.py`)
- Import publishing → Admin database layer: commits imports
- College website resolver → Admin database layer: updates records (evidence: `cet/backend/admin/resolver.py`)
