How tarequzzaman/australia-holidays works
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 main.py · requirements.txt Dependencies · vercel.json Vercel · nt_public_holidays.json Public JSON
Components 13
Clients
External callers of the API
- Client · Browser, script, or service calling the API
API app
FastAPI application and HTTP endpoints
- main.py · Application entrypoint, routing, and shared request handling
main.py - Health · Readiness or health check at /
main.py - Public holidays · Lookup public holidays by state and year
main.py - School holidays · Lookup school holidays by state and year
main.py - School terms · Lookup school term periods by state and year
main.py - Holiday check · Classify whether a date falls in a holiday period
main.py - Lookup logic · Validates query parameters and matches dates/ranges against datasets
main.py
Data files
Local JSON holiday datasets
- Public JSON · NT public holiday records
data/nt_public_holidays.json - School JSON · NT school holiday and term records
data/nt_school_holidays.json
Delivery
Runtime and deployment surfaces
- API docs · Interactive OpenAPI UI exposed by FastAPI
- Dependencies · Runtime dependency set from requirements.txt
requirements.txt - Vercel · Serverless deployment target defined by vercel.json
vercel.json
Connections 15
- 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