# tarequzzaman/australia-holidays architecture

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

- Interactive diagram: https://gitdiagram.com/tarequzzaman/australia-holidays
- Repository: https://github.com/tarequzzaman/australia-holidays

## Overview

1. **Overall shape**
   - This is a small, single-service API repository.
   - The architecture is centered on one Python application (`main.py`) that serves holiday data from local JSON files under `data/`.

2. **Runtime and framework**
   - The service is built with **Python 3.12+** and **FastAPI**.
   - FastAPI provides the HTTP routing, request validation, and the interactive `/docs` API UI mentioned in the README.

3. **Primary application boundary**
   - `main.py` is the main entry point and likely defines the FastAPI app, route handlers, and any shared validation or lookup logic.
   - There is no evidence of separate service layers, background jobs, or multiple deployable components.

4. **Data storage model**
   - Holiday information is not stored in a database.
   - Instead, the API reads from two static JSON datasets:
     - `data/nt_public_holidays.json`
     - `data/nt_school_holidays.json`
   - This makes the repo effectively a read-only data API with local file-based persistence.

5. **Functional subsystems**
   - The API exposes four logical capabilities:
     - health check at `/`
     - public holiday lookup at `/holidays/public`
     - school holiday lookup at `/holidays/school`
     - school term lookup at `/terms/school`
     - date-based holiday classification at `/holidays/check`
   - These are all HTTP endpoints over the same underlying data source.

6. **Request flow**
   - A client sends a request with `state`, `year`, or `date` query parameters.
   - FastAPI validates the request.
   - The application looks up matching records in the JSON holiday files.
   - The response returns either the matched holiday period(s) or a boolean classification for a specific date.

7. **Domain boundaries**
   - The repository models two domain concepts:
     - **public holidays** as date-based events
     - **school holidays/terms** as date ranges
   - The `/holidays/check` endpoint bridges these two datasets by checking whether a given date falls within either category.

8. **Geographic scope**
   - The current implementation is NT-focused.
   - The README explicitly says support for other Australian states and territories is planned, so the architecture should be viewed as state-code-driven but currently backed by NT-only data.

9. **External dependencies and integrations**
   - There is no database, message broker, or third-party API integration visible in the repo.
   - The only external references are the government sources used to curate the JSON data, but those are content sources rather than runtime dependencies.

10. **Deployment**
   - `vercel.json` indicates the API is intended to be deployed on **Vercel**.
   - The live endpoint in the README suggests the repo can run as a serverless or edge-hosted FastAPI deployment, though the core architecture remains the same: HTTP API + local JSON data.

11. **Developer tooling**
   - `requirements.txt` captures Python dependencies.
   - Local development uses `fastapi dev`, and the built-in docs at `/docs` are part of the developer experience and API exploration workflow.

12. **What to draw in an architecture diagram**
   - The clearest diagram is:
     - **Client** → **FastAPI app (`main.py`)** → **JSON data files in `data/`**
   - The endpoints sit in the application layer, and the JSON files are the only persistence layer.
   - There should be no separate database box or service bus box, because neither is part of the current repo architecture.

Main entry points: [`main.py`](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py) (main.py), [`requirements.txt`](https://github.com/tarequzzaman/australia-holidays/blob/main/requirements.txt) (Dependencies), [`vercel.json`](https://github.com/tarequzzaman/australia-holidays/blob/main/vercel.json) (Vercel), [`data/nt_public_holidays.json`](https://github.com/tarequzzaman/australia-holidays/blob/main/data/nt_public_holidays.json) (Public JSON)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_client["Clients"]
  node_client_api(("Client<br/>HTTP caller"))
end

subgraph group_grp_app["API app"]
  node_app_main["main.py<br/>FastAPI app<br/>[main.py]"]
  node_route_root["Health<br/>endpoint<br/>[main.py]"]
  node_route_public["Public holidays<br/>endpoint<br/>[main.py]"]
  node_route_school["School holidays<br/>endpoint<br/>[main.py]"]
  node_route_terms["School terms<br/>endpoint<br/>[main.py]"]
  node_route_check["Holiday check<br/>endpoint<br/>[main.py]"]
  node_logic_lookup["Lookup logic<br/>validation + matching<br/>[main.py]"]
end

subgraph group_grp_data["Data files"]
  node_public_json["Public JSON<br/>holiday dataset"]
  node_school_json["School JSON<br/>holiday dataset"]
end

subgraph group_grp_ops["Delivery"]
  node_docs_ui["API docs"]
  node_deps["Dependencies<br/>Python packages<br/>[requirements.txt]"]
  node_vercel["Vercel<br/>deployment<br/>[vercel.json]"]
end

node_client_api -->|"requests"| node_app_main
node_app_main -->|"serves"| node_route_root
node_app_main -->|"serves"| node_route_public
node_app_main -->|"serves"| node_route_school
node_app_main -->|"serves"| node_route_terms
node_app_main -->|"serves"| node_route_check
node_route_public -->|"uses"| node_logic_lookup
node_route_school -->|"uses"| node_logic_lookup
node_route_terms -->|"uses"| node_logic_lookup
node_route_check -->|"uses"| node_logic_lookup
node_logic_lookup -->|"reads"| node_public_json
node_logic_lookup -->|"reads"| node_school_json
node_app_main -.->|"exposes"| node_docs_ui
node_vercel -.->|"hosts"| node_app_main
node_deps -.->|"supports"| node_app_main

click node_app_main "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_route_root "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_route_public "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_route_school "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_route_terms "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_route_check "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_logic_lookup "https://github.com/tarequzzaman/australia-holidays/blob/main/main.py"
click node_public_json "https://github.com/tarequzzaman/australia-holidays/blob/main/data/nt_public_holidays.json"
click node_school_json "https://github.com/tarequzzaman/australia-holidays/blob/main/data/nt_school_holidays.json"
click node_deps "https://github.com/tarequzzaman/australia-holidays/blob/main/requirements.txt"
click node_vercel "https://github.com/tarequzzaman/australia-holidays/blob/main/vercel.json"

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_client_api toneBlue
class node_app_main,node_route_root,node_route_public,node_route_school,node_route_terms,node_route_check,node_logic_lookup toneAmber
class node_public_json,node_school_json toneMint
class node_docs_ui,node_deps,node_vercel toneRose
```

## Components

### Clients

External callers of the API

- **Client**: HTTP caller · Browser, script, or service calling the API

### API app

FastAPI application and HTTP endpoints

- [main.py](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): FastAPI app · Application entrypoint, routing, and shared request handling · `main.py`
- [Health](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): endpoint · Readiness or health check at / · `main.py`
- [Public holidays](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): endpoint · Lookup public holidays by state and year · `main.py`
- [School holidays](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): endpoint · Lookup school holidays by state and year · `main.py`
- [School terms](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): endpoint · Lookup school term periods by state and year · `main.py`
- [Holiday check](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): endpoint · Classify whether a date falls in a holiday period · `main.py`
- [Lookup logic](https://github.com/tarequzzaman/australia-holidays/blob/main/main.py): validation + matching · Validates query parameters and matches dates/ranges against datasets · `main.py`

### Data files

Local JSON holiday datasets

- [Public JSON](https://github.com/tarequzzaman/australia-holidays/blob/main/data/nt_public_holidays.json): holiday dataset · NT public holiday records · `data/nt_public_holidays.json`
- [School JSON](https://github.com/tarequzzaman/australia-holidays/blob/main/data/nt_school_holidays.json): holiday dataset · NT school holiday and term records · `data/nt_school_holidays.json`

### Delivery

Runtime and deployment surfaces

- **API docs**: FastAPI docs · Interactive OpenAPI UI exposed by FastAPI
- [Dependencies](https://github.com/tarequzzaman/australia-holidays/blob/main/requirements.txt): Python packages · Runtime dependency set from requirements.txt · `requirements.txt`
- [Vercel](https://github.com/tarequzzaman/australia-holidays/blob/main/vercel.json): deployment · Serverless deployment target defined by vercel.json · `vercel.json`

## Connections

- Client → main.py: requests · Clients send HTTP requests to the FastAPI application
- main.py → Health: serves · Defines the health endpoint
- main.py → Public holidays: serves · Defines public holiday lookup
- main.py → School holidays: serves · Defines school holiday lookup
- main.py → School terms: serves · Defines school term lookup
- main.py → Holiday check: serves · Defines date classification endpoint
- Public holidays → Lookup logic: uses · Public holiday endpoint uses shared validation and matching logic
- School holidays → Lookup logic: uses · School holiday endpoint uses shared validation and matching logic
- School terms → Lookup logic: uses · School term endpoint uses shared validation and matching logic
- Holiday check → Lookup logic: uses · Holiday check endpoint uses shared classification logic
- Lookup logic → Public JSON: reads · Matches public holiday data from the JSON file
- Lookup logic → School JSON: reads · Matches school holiday and term data from the JSON file
- main.py → API docs: exposes · FastAPI exposes interactive API documentation
- Vercel → main.py: hosts · Deployment configuration targets the FastAPI app
- Dependencies → main.py: supports · Python package dependencies required to run the service