SwimStats Chile is a data platform for Chilean competitive swimming results, athletes and clubs.
About this repository. This is a public snapshot of SwimStats Chile as it stood in July 2026, published as a portfolio piece. It covers the ingestion and normalization work: PDF parsing, identity curation, validation gates, the PostgreSQL model and the first FastAPI endpoints. Development continues in a private repository, so this snapshot is frozen and does not accept issues or pull requests. See License before reusing any of it.
The project transforms fragmented competition results, mostly published as PDFs or event-specific files, into structured, auditable and queryable data. It combines a backend ingestion pipeline, a PostgreSQL core model, a FastAPI layer and a React frontend.
Swimming results are often published in semi-structured formats that are hard to search, compare or analyze over time. SwimStats Chile turns those sources into normalized data so athletes, clubs and competitions can be explored with better traceability.
The current dataset focuses on Chilean master swimming results, especially public FCHMN result documents, but the product identity intentionally avoids depending on a single federation as its brand.
graph LR
A[Public result sources] --> B[Scraper]
B --> C[Manifest JSONL]
C --> D[PDF downloader]
D --> E[Parser and normalization]
E --> F[Curated CSV materialization]
F --> G[Batch validation gates]
G --> H[(PostgreSQL staging)]
H --> I[(PostgreSQL core)]
I --> J[FastAPI]
J --> K[React frontend]
backend/ Data ingestion pipeline, PostgreSQL schema, FastAPI endpoints and backend tests.
frontend/ React + TypeScript UI consuming API contracts and mock fixtures during integration.
docs/ Cross-project roadmap, plans and portfolio-level documentation.
Operational agent rules and tool-specific metadata may also live at the repository root when required by the development workflow.
- Backend: Python, FastAPI, PostgreSQL, CLI pipelines.
- Data processing: PDF parsing, CSV materialization, staging/core loading, validation gates.
- Frontend: React, TypeScript, Vite, Tailwind CSS, TanStack Query, Zod.
- Documentation: Markdown and Mermaid diagrams.
The sections below describe where the project stood in July 2026, when this snapshot was taken. They are kept as a record of that moment rather than as a current roadmap.
One deliberate exception: the relay module has since received a privacy correction, applied here rather than left in place. It stopped returning national identity numbers and dates of birth to the client, and stopped deriving an athlete's public identifier from one. Everything else is as it stood. The reasoning is in ADR 0003.
Focus at the time:
- Auditable backend pipeline for historical result ingestion.
- Curated athlete and club identity handling before loading data into core tables.
- FastAPI endpoints for athletes, clubs and competition data.
- Frontend foundation with contract-first integration.
Planned at the time:
- OpenAPI-based TypeScript generation from FastAPI contracts.
- Athlete and club profile pages.
- Competition result dashboards.
- Historical performance analysis and rankings.
Everything listed as planned above was subsequently built, along with a body of work this snapshot does not contain. It is summarized here so the repository reads as a stage rather than an endpoint. The implementations live in the private repository; what follows describes the problems, not the solutions.
- Operating a live meet. Running a competition in real time rather than importing it afterwards: heat call boards for the pool deck, an announcement display for spectators, and the synchronization problems that come with several screens reflecting the same event as it unfolds.
- Meet program ingestion. Reading competition programs out of the format meet management software actually exports, and reconciling a published program against results as the event progresses.
- Scoped administrative access. Letting a meet organizer operate their own competition without granting access to anything else.
- Reconciliation gates. Verifying parsed output against its source document atomically, before any of it reaches core tables — extending the validation approach visible in this snapshot to the point of load.
- Standings and participation analysis. Category-aware club standings and cross-competition participation views.
The running product is at swimstats.cl.
This project is intended for educational and portfolio purposes. Data sources may include publicly available swimming competition results. The repository does not represent an official federation platform, and raw/private data should not be committed to version control.
No competition data ships with this repository. The ingestion pipeline reads from local input directories that are excluded from version control, and the test suite runs entirely on synthetic fixtures. Running the pipeline requires supplying your own source documents.
Licensed under the PolyForm Noncommercial License 1.0.0.
In short: you may read, run, modify and share this code for any noncommercial purpose — study, experimentation, teaching, personal projects. Commercial use is not permitted. SwimStats Chile is an active commercial product, and this snapshot is published so the engineering work can be reviewed, not so it can be redeployed.
If you want to use any of it commercially, get in touch.