# ashermustafa7/the_crime_of_the_supreme_court architecture

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

- Interactive diagram: https://gitdiagram.com/ashermustafa7/the_crime_of_the_supreme_court
- Repository: https://github.com/ashermustafa7/the_crime_of_the_supreme_court

## Overview

This repository is a research toolkit for extracting and analyzing Indian Supreme Court case texts, with a focus on crime-related themes and geographic patterns. Its principal workflow is raw judgment text → parsed case records → clustering and seed-based crime labels → map or aggregate views. Separate scripts offer alternative clustering approaches, compare clustering results, and help expand crime-label seeds. The README is only a title, so the map reflects the file tree and sampled scripts; unsampled subsystem wiring is not assumed.

Main entry points: [`scripts/cluster_kmeans_semantic.py`](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_kmeans_semantic.py) (Semantic KMeans), [`scripts/extract_and_parse.py`](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/extract_and_parse.py) (Extract and parse), [`scripts/seed_expansion_helper.py`](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/seed_expansion_helper.py) (Expand crime seeds), [`raw_texts`](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/tree/main/raw_texts) (Judgment texts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Case ingestion"]
  node_raw["Judgment texts"]
  node_extract["Extract and parse"]
  node_cases["Parsed cases"]
end

subgraph group_analysis["Crime analysis"]
  node_semantic["Semantic KMeans"]
  node_seeds["Crime seed map"]
  node_altcluster["Alternative clustering"]
  node_bertopic["BERTopic clustering"]
  node_dbscan["DBSCAN clustering<br/>[cluster_dbscan.py]"]
  node_gmm["GMM clustering<br/>[cluster_gmm.py]"]
  node_lda["LDA topics<br/>[cluster_lda.py]"]
  node_labeled["Labeled clusters"]
end

subgraph group_review["Evaluation and refinement"]
  node_compare["Compare results"]
  node_evaluate["Evaluate clustering"]
  node_evaluate_ext["Extended evaluation"]
  node_expand["Expand crime seeds"]
end

subgraph group_views["Geographic views"]
  node_map["Case map"]
  node_location_counts["Location counts"]
  node_state_counts["State counts"]
  node_year_counts["Year counts"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs extraction"| node_extract
node_raw -->|"reads texts"| node_extract
node_extract -->|"writes cases"| node_cases
node_researcher -->|"runs analysis"| node_semantic
node_cases -->|"reads cases"| node_semantic
node_semantic -->|"reads seeds"| node_seeds
node_semantic -->|"writes labels"| node_labeled
node_cases -->|"reads cases"| node_altcluster
node_cases -->|"reads cases"| node_bertopic
node_cases -->|"reads cases"| node_dbscan
node_cases -->|"reads cases"| node_gmm
node_cases -->|"reads cases"| node_lda
node_labeled -->|"compares outputs"| node_compare
node_labeled -->|"evaluates labels"| node_evaluate
node_labeled -->|"evaluates labels"| node_evaluate_ext
node_labeled -->|"reviews clusters"| node_expand
node_expand -->|"updates suggestions"| node_seeds
node_labeled -->|"plots cases"| node_map
node_labeled -->|"groups locations"| node_location_counts
node_labeled -->|"counts states"| node_state_counts
node_labeled -->|"counts years"| node_year_counts

click node_raw "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/tree/main/raw_texts"
click node_extract "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/extract_and_parse.py"
click node_semantic "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_kmeans_semantic.py"
click node_altcluster "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_and_topics.py"
click node_bertopic "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_bertopic.py"
click node_dbscan "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_dbscan.py"
click node_gmm "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_gmm.py"
click node_lda "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_lda.py"
click node_compare "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/compare_cluster_results.py"
click node_evaluate "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/evaluate_clustering.py"
click node_evaluate_ext "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/evaluate_clustering_extended.py"
click node_expand "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/seed_expansion_helper.py"
click node_map "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/map_cases_dash_sample.py"
click node_location_counts "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_location.py"
click node_state_counts "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_state.py"
click node_year_counts "https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_year.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_raw,node_extract,node_cases toneBlue
class node_semantic,node_seeds,node_altcluster,node_bertopic,node_dbscan,node_gmm,node_lda,node_labeled toneAmber
class node_compare,node_evaluate,node_evaluate_ext,node_expand toneMint
class node_map,node_location_counts,node_state_counts,node_year_counts toneRose
class node_researcher toneIndigo
```

## Components

### Case ingestion

- [Judgment texts](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/tree/main/raw_texts): `raw_texts`
- [Extract and parse](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/extract_and_parse.py): `scripts/extract_and_parse.py`
- **Parsed cases**

### Crime analysis

- [Semantic KMeans](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_kmeans_semantic.py): `scripts/cluster_kmeans_semantic.py`
- **Crime seed map**
- [Alternative clustering](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_and_topics.py): `scripts/cluster_and_topics.py`
- [BERTopic clustering](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_bertopic.py): `scripts/cluster_bertopic.py`
- [DBSCAN clustering](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_dbscan.py): `scripts/cluster_dbscan.py`
- [GMM clustering](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_gmm.py): `scripts/cluster_gmm.py`
- [LDA topics](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/cluster_lda.py): `scripts/cluster_lda.py`
- **Labeled clusters**

### Evaluation and refinement

- [Compare results](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/compare_cluster_results.py): `scripts/compare_cluster_results.py`
- [Evaluate clustering](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/evaluate_clustering.py): `scripts/evaluate_clustering.py`
- [Extended evaluation](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/evaluate_clustering_extended.py): `scripts/evaluate_clustering_extended.py`
- [Expand crime seeds](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/seed_expansion_helper.py): `scripts/seed_expansion_helper.py`

### Geographic views

- [Case map](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/map_cases_dash_sample.py): `scripts/map_cases_dash_sample.py`
- [Location counts](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_location.py): `scripts/count_cases_by_location.py`
- [State counts](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_state.py): `scripts/count_cases_by_state.py`
- [Year counts](https://github.com/ashermustafa7/the_crime_of_the_supreme_court/blob/main/scripts/count_cases_by_year.py): `scripts/count_cases_by_year.py`

### Other components

- **Researcher**

## Connections

- Researcher → Extract and parse: runs extraction
- Judgment texts → Extract and parse: reads texts
- Extract and parse → Parsed cases: writes cases
- Researcher → Semantic KMeans: runs analysis
- Parsed cases → Semantic KMeans: reads cases
- Semantic KMeans → Crime seed map: reads seeds
- Semantic KMeans → Labeled clusters: writes labels
- Parsed cases → Alternative clustering: reads cases
- Parsed cases → BERTopic clustering: reads cases
- Parsed cases → DBSCAN clustering: reads cases
- Parsed cases → GMM clustering: reads cases
- Parsed cases → LDA topics: reads cases
- Labeled clusters → Compare results: compares outputs
- Labeled clusters → Evaluate clustering: evaluates labels
- Labeled clusters → Extended evaluation: evaluates labels
- Labeled clusters → Expand crime seeds: reviews clusters
- Expand crime seeds → Crime seed map: updates suggestions
- Labeled clusters → Case map: plots cases
- Labeled clusters → Location counts: groups locations
- Labeled clusters → State counts: counts states
- Labeled clusters → Year counts: counts years
