# hipo/university-domains-list architecture

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

- Interactive diagram: https://gitdiagram.com/hipo/university-domains-list
- Repository: https://github.com/hipo/university-domains-list

## Overview

1. This repository is primarily a **data distribution repo**, not a full application. Its core asset is a single canonical dataset: `world_universities_and_domains.json`, which contains university names, countries, ISO country codes, domains, and web pages.

2. The dataset is the main architectural boundary. Everything else in the repo exists to **filter, validate, format, and continuously check** that JSON file rather than to serve business logic or a UI.

3. `filter.py` is the only visible code artifact in the root that performs data transformation. Based on the README, it acts as a **country-based filter utility**: given one or more country names, it emits a reduced JSON file (`filtered_world_universities_and_domains.json`) for smaller downstream payloads.

4. The data flow is straightforward: **canonical JSON in → optional filter step → smaller JSON out**. There is no database, message queue, or backend service in this repo; the dataset itself is the source of truth.

5. The `tests/` directory suggests the repository treats the data file as a product that must be machine-checked. The test files indicate coverage for:
   - duplicate detection,
   - filter behavior,
   - formatting rules,
   - schema/structure validation.
   This implies the repo’s main risk is data integrity, not runtime logic.

6. `tests/base_test.py` and `tests/requirements.txt` indicate a lightweight Python test harness around the dataset and filter script. The tests are likely designed to run in CI and verify both the JSON payload and the utility script behavior.

7. The `.github/workflows/` folder shows the CI/CD boundary. `lint-test.yml` is the primary quality gate, `deploy.yml` suggests publication or release automation, and `ai-pr-review.py` / `ai-review.yml` add automated review assistance. These workflows are around the repository, not inside the runtime path.

8. Local development tooling is centered on code/data hygiene: `.pre-commit-config.yaml`, `.prettierrc`, and the docs in `docs/local_linting_guide.md` and `docs/local_testing_guide.md`. This reinforces that maintainability and consistency are first-class concerns for the dataset.

9. The README’s “hosted API” and “built-in API” references describe **external consumption paths**, not an in-repo server implementation. The hosted API is served by a separate project/package (`university-domains-list-api`), while this repo provides the underlying data source.

10. In diagram terms, the architecture is best represented as:
    - **Source data:** `world_universities_and_domains.json`
    - **Transform utility:** `filter.py`
    - **Validation layer:** `tests/`
    - **Automation layer:** GitHub Actions + pre-commit/tooling
    - **Consumers:** direct JSON readers, the hosted API, or downstream users filtering the dataset locally

11. The overall design is simple but important: a **single authoritative dataset** with a small supporting toolchain that ensures the file stays valid and can be selectively reduced for downstream use cases such as email-domain validation or university lookup.

Main entry points: [`tests`](https://github.com/hipo/university-domains-list/tree/master/tests) (Test suite), [`world_universities_and_domains.json`](https://github.com/hipo/university-domains-list/blob/master/world_universities_and_domains.json) (Universities JSON), [`filter.py`](https://github.com/hipo/university-domains-list/blob/master/filter.py) (Filter script), [`.github/workflows/lint-test.yml`](https://github.com/hipo/university-domains-list/blob/master/.github/workflows/lint-test.yml) (Lint & test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data"]
  node_world_universities_and_domains_json[("Universities JSON<br/>canonical dataset")]
  node_filtered_world_universities_and_domains_json[("Filtered JSON<br/>derived dataset")]
end

subgraph group_tooling["Tooling"]
  node_filter_py["Filter script<br/>transform utility<br/>[filter.py]"]
  node_local_guides["Dev guides<br/>docs"]
  node_precommit["Pre-commit<br/>local hook config"]
end

subgraph group_validation["Validation"]
  node_test_suite["Test suite<br/>python tests"]
  node_duplicate_checks["Duplicates<br/>integrity test<br/>[test_duplicates.py]"]
  node_filter_checks["Filter tests<br/>behavior test<br/>[test_filter.py]"]
  node_format_checks["Format tests<br/>quality test<br/>[test_format.py]"]
  node_schema_checks["Schema tests<br/>structure test<br/>[test_schema.py]"]
end

subgraph group_automation["Automation"]
  node_lint_test_workflow["Lint & test<br/>ci workflow<br/>[lint-test.yml]"]
  node_deploy_workflow["Deploy<br/>release workflow<br/>[deploy.yml]"]
  node_ai_review_workflow["AI review<br/>review workflow<br/>[ai-review.yml]"]
  node_ai_pr_review_script["AI review script<br/>automation script<br/>[ai-pr-review.py]"]
end

subgraph group_consumers["Consumers"]
  node_hosted_api(("Hosted API<br/>external service"))
  node_downstream_users(("Downstream users<br/>external consumers"))
end

node_world_universities_and_domains_json -->|"source"| node_filter_py
node_filter_py -->|"produces"| node_filtered_world_universities_and_domains_json
node_world_universities_and_domains_json -->|"validated by"| node_test_suite
node_filter_py -->|"validated by"| node_test_suite
node_test_suite -->|"includes"| node_duplicate_checks
node_test_suite -->|"includes"| node_filter_checks
node_test_suite -->|"includes"| node_format_checks
node_test_suite -->|"includes"| node_schema_checks
node_lint_test_workflow -->|"runs"| node_test_suite
node_lint_test_workflow -.->|"aligns with"| node_precommit
node_deploy_workflow -->|"publishes"| node_world_universities_and_domains_json
node_ai_review_workflow -->|"invokes"| node_ai_pr_review_script
node_ai_review_workflow -.->|"reviews against"| node_test_suite
node_local_guides -.->|"documents"| node_filter_py
node_local_guides -.->|"documents"| node_test_suite
node_hosted_api -->|"consumes"| node_world_universities_and_domains_json
node_downstream_users -->|"reads"| node_world_universities_and_domains_json
node_downstream_users -->|"reads"| node_filtered_world_universities_and_domains_json

click node_world_universities_and_domains_json "https://github.com/hipo/university-domains-list/blob/master/world_universities_and_domains.json"
click node_filter_py "https://github.com/hipo/university-domains-list/blob/master/filter.py"
click node_test_suite "https://github.com/hipo/university-domains-list/tree/master/tests"
click node_duplicate_checks "https://github.com/hipo/university-domains-list/blob/master/tests/test_duplicates.py"
click node_filter_checks "https://github.com/hipo/university-domains-list/blob/master/tests/test_filter.py"
click node_format_checks "https://github.com/hipo/university-domains-list/blob/master/tests/test_format.py"
click node_schema_checks "https://github.com/hipo/university-domains-list/blob/master/tests/test_schema.py"
click node_lint_test_workflow "https://github.com/hipo/university-domains-list/blob/master/.github/workflows/lint-test.yml"
click node_deploy_workflow "https://github.com/hipo/university-domains-list/blob/master/.github/workflows/deploy.yml"
click node_ai_review_workflow "https://github.com/hipo/university-domains-list/blob/master/.github/workflows/ai-review.yml"
click node_ai_pr_review_script "https://github.com/hipo/university-domains-list/blob/master/.github/workflows/ai-pr-review.py"
click node_precommit "https://github.com/hipo/university-domains-list/blob/master/.pre-commit-config.yaml"

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_world_universities_and_domains_json,node_filtered_world_universities_and_domains_json toneBlue
class node_filter_py,node_local_guides,node_precommit toneAmber
class node_test_suite,node_duplicate_checks,node_filter_checks,node_format_checks,node_schema_checks toneMint
class node_lint_test_workflow,node_deploy_workflow,node_ai_review_workflow,node_ai_pr_review_script toneRose
class node_hosted_api,node_downstream_users toneIndigo
```

## Components

### Data

Canonical dataset and derived output

- [Universities JSON](https://github.com/hipo/university-domains-list/blob/master/world_universities_and_domains.json): canonical dataset · Single source of truth for university names, countries, domains, and web pages · `world_universities_and_domains.json`
- **Filtered JSON**: derived dataset · Country-reduced output produced by the filter utility

### Tooling

Local scripts and developer guides

- [Filter script](https://github.com/hipo/university-domains-list/blob/master/filter.py): transform utility · Creates a smaller JSON payload from selected countries · `filter.py`
- **Dev guides**: docs · Local linting and testing guidance for contributors
- [Pre-commit](https://github.com/hipo/university-domains-list/blob/master/.pre-commit-config.yaml): local hook config · Local hygiene checks before commits · `.pre-commit-config.yaml`

### Validation

Checks that protect data integrity

- [Test suite](https://github.com/hipo/university-domains-list/tree/master/tests): python tests · Machine checks for data integrity and filter behavior · `tests`
- [Duplicates](https://github.com/hipo/university-domains-list/blob/master/tests/test_duplicates.py): integrity test · Detects repeated or conflicting entries · `tests/test_duplicates.py`
- [Filter tests](https://github.com/hipo/university-domains-list/blob/master/tests/test_filter.py): behavior test · Verifies country-based filtering output · `tests/test_filter.py`
- [Format tests](https://github.com/hipo/university-domains-list/blob/master/tests/test_format.py): quality test · Enforces formatting expectations for the JSON payload · `tests/test_format.py`
- [Schema tests](https://github.com/hipo/university-domains-list/blob/master/tests/test_schema.py): structure test · Validates JSON structure and required fields · `tests/test_schema.py`

### Automation

CI, review, and release workflows

- [Lint & test](https://github.com/hipo/university-domains-list/blob/master/.github/workflows/lint-test.yml): ci workflow · Primary CI gate for validation and hygiene · `.github/workflows/lint-test.yml`
- [Deploy](https://github.com/hipo/university-domains-list/blob/master/.github/workflows/deploy.yml): release workflow · Publishes or packages the dataset for downstream use · `.github/workflows/deploy.yml`
- [AI review](https://github.com/hipo/university-domains-list/blob/master/.github/workflows/ai-review.yml): review workflow · Automated review assistance for pull requests · `.github/workflows/ai-review.yml`
- [AI review script](https://github.com/hipo/university-domains-list/blob/master/.github/workflows/ai-pr-review.py): automation script · Script used by the AI review workflow · `.github/workflows/ai-pr-review.py`

### Consumers

Ways the dataset is used outside the repo

- **Hosted API**: external service · Separate consumer service built from this dataset
- **Downstream users**: external consumers · Local readers and tools that consume the JSON directly

## Connections

- Universities JSON → Filter script: source · The canonical dataset is the input to filtering
- Filter script → Filtered JSON: produces · Creates a reduced dataset for selected countries
- Universities JSON → Test suite: validated by · Core tests guard the canonical data file
- Filter script → Test suite: validated by · Filter behavior is covered by the test suite
- Test suite → Duplicates: includes · Duplicate detection is one validation slice
- Test suite → Filter tests: includes · Filter behavior is one validation slice
- Test suite → Format tests: includes · Formatting rules are one validation slice
- Test suite → Schema tests: includes · Schema checks are one validation slice
- Lint & test → Test suite: runs · CI executes the repository checks
- Lint & test → Pre-commit: aligns with · CI mirrors local hygiene rules
- Deploy → Universities JSON: publishes · Release automation centers on the canonical dataset
- AI review → AI review script: invokes · Workflow runs the review helper script
- AI review → Test suite: reviews against · Automated review is oriented around repository quality checks
- Dev guides → Filter script: documents · Guides explain local filtering and linting
- Dev guides → Test suite: documents · Guides explain how to run validation locally
- Hosted API → Universities JSON: consumes · Separate API project uses this repo as its data source
- Downstream users → Universities JSON: reads · Users can consume the canonical JSON directly
- Downstream users → Filtered JSON: reads · Users can also consume the filtered output