# sergicasesalonso/pompeu-data-team architecture

> Architecture diagram of the GitHub repository sergicasesalonso/pompeu-data-team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sergicasesalonso/pompeu-data-team
- Repository: https://github.com/sergicasesalonso/pompeu-data-team

## Overview

Pompeu is a football-possession inference system for the More than a Hack challenge: it turns match tracking and match context into one H/A/D/X label per frame, then validates and scores that submission. The principal path runs from tracking ingestion through cleaning and feature/event extraction, into a selected model and sequence decoder, and finally to CSV output. The repository also supports video-based ball recovery, external-data and learned experts, and robustness evaluation. Some of these branches are documented or indexed but were not sampled, so their internal links are omitted.

Main entry points: [`pompeu/features/build.py`](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/build.py) (Feature builder), [`pompeu/models/hsmm.py`](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/models/hsmm.py) (HSMM inference), [`pompeu/pipeline.py`](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/pipeline.py) (Prediction pipeline), [`pompeu/validate/harness.py`](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/validate/harness.py) (Validation harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and tracking"]
  node_match_data(("Match assets"))
  node_game_config["Game alignment<br/>[games.py]"]
  node_tracking_io["Tracking loaders<br/>[atd.py]"]
  node_tracking_contract["Tracking contract<br/>[contract.py]"]
  node_cleaning["Tracking cleaning<br/>[__init__.py]"]
  node_path_config["Repository paths<br/>[paths.py]"]
end

subgraph group_inference["Possession inference"]
  node_kinematics["Motion features<br/>[kinematics.py]"]
  node_feature_builder["Feature builder<br/>[build.py]"]
  node_context_features["Match context<br/>[context.py]"]
  node_touch_events["Touch events<br/>[touches.py]"]
  node_deadball["Dead-ball detection<br/>[deadball.py]"]
  node_rules_model["Rule model<br/>[rules.py]"]
  node_hsmm_model["HSMM inference<br/>[hsmm.py]"]
  node_sequence_decode["Viterbi decoder<br/>[viterbi.py]"]
  node_pipeline["Prediction pipeline<br/>[pipeline.py]"]
  node_submission["Submission CSV<br/>[make_submission.py]"]
end

subgraph group_learning["Experts and vision"]
  node_video_assets(("Broadcast video"))
  node_video_fusion["Video ball fusion<br/>[fuse.py]"]
  node_external_data(("External matches"))
  node_external_examples["External examples<br/>[examples.py]"]
  node_data_degradation["Data degradation<br/>[degrade.py]"]
  node_synthetic_tags["Synthetic tags<br/>[synthetic_tags.py]"]
  node_tcn_expert["TCN expert<br/>[tcn.py]"]
end

subgraph group_evaluation["Validation and scoring"]
  node_robustness["Stress validation<br/>[stress.py]"]
  node_validation_harness["Validation harness<br/>[harness.py]"]
  node_ground_truth["Public ground truth<br/>[gt.py]"]
  node_scoring["Possession metrics"]
  node_evaluator["Evaluation runner<br/>[run_evaluation.py]"]
end

node_match_data -->|"supplies data"| node_tracking_io
node_game_config -->|"defines alignment"| node_tracking_contract
node_tracking_io -->|"loads tracking"| node_tracking_contract
node_tracking_contract -->|"provides tracking"| node_cleaning
node_pipeline -->|"cleans tracking"| node_cleaning
node_cleaning -->|"uses motion features"| node_kinematics
node_feature_builder -->|"computes motion"| node_kinematics
node_feature_builder -->|"builds context"| node_context_features
node_context_features -->|"reads match constants"| node_game_config
node_touch_events -->|"uses motion"| node_kinematics
node_deadball -->|"uses motion"| node_kinematics
node_deadball -->|"uses features"| node_feature_builder
node_rules_model -->|"uses events"| node_deadball
node_rules_model -->|"uses events"| node_touch_events
node_hsmm_model -->|"builds evidence"| node_feature_builder
node_hsmm_model -->|"uses detection"| node_deadball
node_hsmm_model -->|"uses events"| node_touch_events
node_hsmm_model -->|"uses rule labels"| node_rules_model
node_hsmm_model -->|"decodes states"| node_sequence_decode
node_pipeline -->|"dispatches method"| node_rules_model
node_pipeline -->|"dispatches method"| node_hsmm_model
node_pipeline -->|"dispatches method"| node_tcn_expert
node_pipeline -.->|"provides predictions"| node_submission
node_video_assets -.->|"provides video"| node_video_fusion
node_external_data -.->|"provides matches"| node_external_examples
node_external_examples -->|"degrades examples"| node_data_degradation
node_external_examples -->|"builds features"| node_feature_builder
node_synthetic_tags -->|"injects context"| node_feature_builder
node_tcn_expert -->|"builds features"| node_feature_builder
node_validation_harness -->|"runs predictions"| node_pipeline
node_validation_harness -->|"runs stress checks"| node_robustness
node_validation_harness -->|"loads truth"| node_ground_truth
node_validation_harness -->|"computes scores"| node_scoring
node_evaluator -->|"scores submissions"| node_scoring
node_path_config -->|"sets data paths"| node_tracking_io
node_path_config -->|"sets data paths"| node_external_examples

click node_game_config "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/games.py"
click node_tracking_io "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/atd.py"
click node_tracking_contract "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/contract.py"
click node_cleaning "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/clean/__init__.py"
click node_kinematics "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/kinematics.py"
click node_feature_builder "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/build.py"
click node_context_features "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/context.py"
click node_touch_events "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/events/touches.py"
click node_deadball "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/events/deadball.py"
click node_rules_model "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/models/rules.py"
click node_hsmm_model "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/models/hsmm.py"
click node_sequence_decode "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/decode/viterbi.py"
click node_pipeline "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/pipeline.py"
click node_submission "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/scripts/make_submission.py"
click node_video_fusion "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/vision/fuse.py"
click node_external_examples "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/examples.py"
click node_data_degradation "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/degrade.py"
click node_synthetic_tags "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/synthetic_tags.py"
click node_tcn_expert "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/experimental/tcn.py"
click node_robustness "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/validate/stress.py"
click node_validation_harness "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/validate/harness.py"
click node_ground_truth "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/gt.py"
click node_scoring "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/evaluation/possession_metrics.py"
click node_evaluator "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/evaluation/run_evaluation.py"
click node_path_config "https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/paths.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_match_data,node_game_config,node_tracking_io,node_tracking_contract,node_cleaning,node_path_config toneBlue
class node_kinematics,node_feature_builder,node_context_features,node_touch_events,node_deadball,node_rules_model,node_hsmm_model,node_sequence_decode,node_pipeline,node_submission toneAmber
class node_video_assets,node_video_fusion,node_external_data,node_external_examples,node_data_degradation,node_synthetic_tags,node_tcn_expert toneMint
class node_robustness,node_validation_harness,node_ground_truth,node_scoring,node_evaluator toneRose
```

## Components

### Inputs and tracking

- **Match assets**
- [Game alignment](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/games.py): `games.py`
- [Tracking loaders](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/atd.py): `pompeu/io/atd.py`
- [Tracking contract](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/contract.py): `pompeu/io/contract.py`
- [Tracking cleaning](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/clean/__init__.py): `pompeu/clean/__init__.py`
- [Repository paths](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/paths.py): `pompeu/paths.py`

### Possession inference

- [Motion features](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/kinematics.py): `pompeu/features/kinematics.py`
- [Feature builder](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/build.py): `pompeu/features/build.py`
- [Match context](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/features/context.py): `pompeu/features/context.py`
- [Touch events](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/events/touches.py): `pompeu/events/touches.py`
- [Dead-ball detection](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/events/deadball.py): `pompeu/events/deadball.py`
- [Rule model](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/models/rules.py): `pompeu/models/rules.py`
- [HSMM inference](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/models/hsmm.py): `pompeu/models/hsmm.py`
- [Viterbi decoder](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/decode/viterbi.py): `pompeu/decode/viterbi.py`
- [Prediction pipeline](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/pipeline.py): `pompeu/pipeline.py`
- [Submission CSV](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/scripts/make_submission.py): `scripts/make_submission.py`

### Experts and vision

- **Broadcast video**
- [Video ball fusion](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/vision/fuse.py): `pompeu/vision/fuse.py`
- **External matches**
- [External examples](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/examples.py): `pompeu/external/examples.py`
- [Data degradation](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/degrade.py): `pompeu/external/degrade.py`
- [Synthetic tags](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/external/synthetic_tags.py): `pompeu/external/synthetic_tags.py`
- [TCN expert](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/experimental/tcn.py): `pompeu/experimental/tcn.py`

### Validation and scoring

- [Stress validation](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/validate/stress.py): `pompeu/validate/stress.py`
- [Validation harness](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/validate/harness.py): `pompeu/validate/harness.py`
- [Public ground truth](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/pompeu/io/gt.py): `pompeu/io/gt.py`
- [Possession metrics](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/evaluation/possession_metrics.py): `evaluation/possession_metrics.py`
- [Evaluation runner](https://github.com/sergicasesalonso/pompeu-data-team/blob/main/evaluation/run_evaluation.py): `evaluation/run_evaluation.py`

## Connections

- Match assets → Tracking loaders: supplies data
- Game alignment → Tracking contract: defines alignment (evidence: `pompeu/io/contract.py`)
- Tracking loaders → Tracking contract: loads tracking (evidence: `pompeu/io/atd.py`)
- Tracking contract → Tracking cleaning: provides tracking (evidence: `pompeu/clean/__init__.py`)
- Prediction pipeline → Tracking cleaning: cleans tracking (evidence: `pompeu/pipeline.py`)
- Tracking cleaning → Motion features: uses motion features
- Feature builder → Motion features: computes motion (evidence: `pompeu/features/build.py`)
- Feature builder → Match context: builds context (evidence: `pompeu/features/build.py`)
- Match context → Game alignment: reads match constants (evidence: `pompeu/features/context.py`)
- Touch events → Motion features: uses motion (evidence: `pompeu/events/touches.py`)
- Dead-ball detection → Motion features: uses motion (evidence: `pompeu/events/deadball.py`)
- Dead-ball detection → Feature builder: uses features (evidence: `pompeu/events/deadball.py`)
- Rule model → Dead-ball detection: uses events (evidence: `pompeu/models/rules.py`)
- Rule model → Touch events: uses events (evidence: `pompeu/models/rules.py`)
- HSMM inference → Feature builder: builds evidence (evidence: `pompeu/models/hsmm.py`)
- HSMM inference → Dead-ball detection: uses detection (evidence: `pompeu/models/hsmm.py`)
- HSMM inference → Touch events: uses events (evidence: `pompeu/models/hsmm.py`)
- HSMM inference → Rule model: uses rule labels (evidence: `pompeu/models/hsmm.py`)
- HSMM inference → Viterbi decoder: decodes states (evidence: `pompeu/models/hsmm.py`)
- Prediction pipeline → Rule model: dispatches method (evidence: `pompeu/pipeline.py`)
- Prediction pipeline → HSMM inference: dispatches method (evidence: `pompeu/pipeline.py`)
- Prediction pipeline → TCN expert: dispatches method (evidence: `pompeu/pipeline.py`)
- Prediction pipeline → Submission CSV: provides predictions
- Broadcast video → Video ball fusion: provides video
- External matches → External examples: provides matches
- External examples → Data degradation: degrades examples (evidence: `pompeu/external/examples.py`)
- External examples → Feature builder: builds features (evidence: `pompeu/external/examples.py`)
- Synthetic tags → Feature builder: injects context (evidence: `pompeu/external/synthetic_tags.py`)
- TCN expert → Feature builder: builds features (evidence: `pompeu/experimental/tcn.py`)
- Validation harness → Prediction pipeline: runs predictions (evidence: `pompeu/validate/harness.py`)
- Validation harness → Stress validation: runs stress checks (evidence: `pompeu/validate/harness.py`)
- Validation harness → Public ground truth: loads truth (evidence: `pompeu/validate/harness.py`)
- Validation harness → Possession metrics: computes scores (evidence: `pompeu/validate/harness.py`)
- Evaluation runner → Possession metrics: scores submissions (evidence: `evaluation/run_evaluation.py`)
- Repository paths → Tracking loaders: sets data paths (evidence: `pompeu/io/atd.py`)
- Repository paths → External examples: sets data paths (evidence: `pompeu/external/examples.py`)
