# abhibarman/fde-aviation architecture

> Architecture diagram of the GitHub repository abhibarman/fde-aviation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhibarman/fde-aviation
- Repository: https://github.com/abhibarman/fde-aviation

## Overview

#### Purpose and Entry Points
This is a training challenge repository for investigating a fictional aviation disruption and producing evidence-backed domain, architecture, and intervention proposals. The primary participant workflow begins with the ordered case material in `case-study/` and synthetic operational evidence in `data/raw/`.

A small Python application layer also exists:
- Streamlit UI entry point: `streamlit_app.py`
- Package/application entry point: `aeronexus/main.py`
- Package exports: `aeronexus/__init__.py`

#### Evidence-First Investigation Boundary
The case-study documents define the business scenario, constraints, stakeholders, event timeline, source systems, and expected deliverables. They are the governing business-evidence layer rather than an implemented production system.
- `case-study/00_challenge_brief.md`
- `case-study/02_incident_timeline.md`
- `case-study/05_constraints_and_authorities.md`

A critical boundary is that conclusions must preserve provenance and contradictions; no individual source is assumed authoritative, and the repository explicitly excludes automation of regulated aviation decisions.

#### Raw Operational Data Layer
Synthetic, unlabelled source-system extracts supply the material for discovery, reconciliation, and derived findings. The data is file-oriented rather than backed by declared infrastructure or a database.
- Flight and resource records: `data/raw/flights.csv`, `data/raw/gate_resources.csv`
- Operational/event feeds: `data/raw/disruption_events.jsonl`, `data/raw/operational_messages.jsonl`
- Cross-domain dependencies: `data/raw/passenger_connections.csv`, `data/raw/crew_assignments.csv`, `data/raw/maintenance_deferrals.csv`

Reference definitions in `data/reference/data_dictionary.csv` provide neutral field/file descriptions, not a preselected target model.

#### AeroNexus Application Core
The Python package appears to encapsulate the application’s evidence and operational-ontology concerns:
- Evidence handling: `aeronexus/evidence.py`
- Ontology/domain representation: `aeronexus/ontology.py`
- Application composition or API-facing behavior: `aeronexus/main.py`

The intended control flow is raw evidence → provenance-aware evidence interpretation → operational ontology/domain views → interactive or API-consumable presentation. Tests indicate contracts around the application, evidence, and ontology boundaries:
- `tests/test_api_contract.py`
- `tests/test_evidence.py`
- `tests/test_ontology.py`

#### Interactive Presentation Boundary
`streamlit_app.py` is the material UI/runtime integration point. It likely consumes the `aeronexus` package rather than embedding the domain model directly, separating interface concerns from evidence and ontology logic. Streamlit is the only explicitly identifiable runtime/service integration from the repository tree; no cloud platform, database, message broker, or external live aviation service is prescribed.

#### Participant Delivery Pipeline
The repository structures work as a staged engineering process: discovery and framing, domain modeling, architecture/decision records, application hypothesis, evaluation, and final proposal.
- Instructions: `participant-prompts/01_discovery.md`, `participant-prompts/06_application.md`
- Blank deliverable formats: `templates/05_bounded_context_canvas.md`, `templates/10_adr.md`, `templates/11_traceability.csv`
- Output locations/examples: `participant-outputs/README.md`, `participant-outputs/08_final_proposal.md`

Traceability is the central cross-cutting requirement: findings and design choices should connect back to raw data and case evidence, while clearly distinguishing facts, derivations, hypotheses, and unresolved questions.

#### Operational Safety and Scope
The system is an analytical and decision-support training artifact, not an aviation operations authority. It must not determine airworthiness, dispatchability, crew legality, runway clearance, or gate authorization. The architecture therefore requires a deliberate human/authorized-system decision boundary grounded in `case-study/05_constraints_and_authorities.md` and the challenge rules in `README.md`.

Main entry points: [`aeronexus/evidence.py`](https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/evidence.py) (Evidence interpretation), [`templates/11_traceability.csv`](https://github.com/abhibarman/fde-aviation/blob/main/templates/11_traceability.csv) (Traceability record), [`aeronexus/ontology.py`](https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/ontology.py) (Operational ontology), [`case-study/05_constraints_and_authorities.md`](https://github.com/abhibarman/fde-aviation/blob/main/case-study/05_constraints_and_authorities.md) (Constraints & authorities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_case["Case Evidence"]
  node_brief["Challenge brief<br/>case document"]
  node_timeline["Incident timeline<br/>case document"]
  node_authorities["Constraints &amp; authorities<br/>safety boundary"]
  node_challenge_rules["Challenge rules<br/>scope rules<br/>[README.md]"]
end

subgraph group_data["Operational Evidence"]
  node_raw_flights["Flight &amp; gate records<br/>CSV extracts<br/>[flights.csv]"]
  node_raw_events["Disruption &amp; message feeds<br/>JSONL extracts"]
  node_raw_dependencies["Passenger, crew &amp; maintenance<br/>CSV extracts"]
  node_dictionary["Data dictionary<br/>reference definitions"]
end

subgraph group_app["AeroNexus Application"]
  node_evidence["Evidence interpretation<br/>provenance layer<br/>[evidence.py]"]
  node_ontology["Operational ontology<br/>domain model<br/>[ontology.py]"]
  node_app_main["Application composition<br/>package entry point<br/>[main.py]"]
  node_streamlit["Streamlit UI<br/>interactive runtime<br/>[streamlit_app.py]"]
end

subgraph group_delivery["Participant Delivery"]
  node_discovery_prompt["Discovery guidance<br/>participant instruction<br/>[01_discovery.md]"]
  node_application_prompt["Application guidance<br/>participant instruction<br/>[06_application.md]"]
  node_model_canvas["Bounded-context canvas<br/>deliverable template"]
  node_adr["Architecture decisions<br/>ADR template<br/>[10_adr.md]"]
  node_traceability["Traceability record<br/>CSV template"]
  node_final_proposal["Final proposal<br/>participant output"]
end

node_brief -->|"frames investigation"| node_discovery_prompt
node_timeline -->|"case evidence"| node_evidence
node_authorities -.->|"constrains proposals"| node_ontology
node_challenge_rules -.->|"limits decision support"| node_streamlit
node_raw_flights -->|"source records"| node_evidence
node_raw_events -->|"event evidence"| node_evidence
node_raw_dependencies -->|"dependency evidence"| node_evidence
node_dictionary -.->|"interprets fields"| node_evidence
node_evidence -->|"provenance-aware findings"| node_ontology
node_ontology -->|"domain views"| node_app_main
node_app_main -->|"powers UI"| node_streamlit
node_discovery_prompt -->|"guides modeling"| node_model_canvas
node_application_prompt -->|"guides architecture"| node_adr
node_evidence -->|"sources findings"| node_traceability
node_model_canvas -->|"records boundaries"| node_traceability
node_adr -->|"records choices"| node_traceability
node_traceability -->|"evidence-backed proposal"| node_final_proposal
node_authorities -.->|"safety scope"| node_final_proposal

click node_brief "https://github.com/abhibarman/fde-aviation/blob/main/case-study/00_challenge_brief.md"
click node_timeline "https://github.com/abhibarman/fde-aviation/blob/main/case-study/02_incident_timeline.md"
click node_authorities "https://github.com/abhibarman/fde-aviation/blob/main/case-study/05_constraints_and_authorities.md"
click node_raw_flights "https://github.com/abhibarman/fde-aviation/blob/main/data/raw/flights.csv"
click node_raw_events "https://github.com/abhibarman/fde-aviation/blob/main/data/raw/disruption_events.jsonl"
click node_raw_dependencies "https://github.com/abhibarman/fde-aviation/blob/main/data/raw/passenger_connections.csv"
click node_dictionary "https://github.com/abhibarman/fde-aviation/blob/main/data/reference/data_dictionary.csv"
click node_evidence "https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/evidence.py"
click node_ontology "https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/ontology.py"
click node_app_main "https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/main.py"
click node_streamlit "https://github.com/abhibarman/fde-aviation/blob/main/streamlit_app.py"
click node_discovery_prompt "https://github.com/abhibarman/fde-aviation/blob/main/participant-prompts/01_discovery.md"
click node_application_prompt "https://github.com/abhibarman/fde-aviation/blob/main/participant-prompts/06_application.md"
click node_model_canvas "https://github.com/abhibarman/fde-aviation/blob/main/templates/05_bounded_context_canvas.md"
click node_adr "https://github.com/abhibarman/fde-aviation/blob/main/templates/10_adr.md"
click node_traceability "https://github.com/abhibarman/fde-aviation/blob/main/templates/11_traceability.csv"
click node_final_proposal "https://github.com/abhibarman/fde-aviation/blob/main/participant-outputs/08_final_proposal.md"
click node_challenge_rules "https://github.com/abhibarman/fde-aviation/blob/main/README.md"

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_brief,node_timeline,node_authorities,node_challenge_rules toneBlue
class node_raw_flights,node_raw_events,node_raw_dependencies,node_dictionary toneAmber
class node_evidence,node_ontology,node_app_main,node_streamlit toneMint
class node_discovery_prompt,node_application_prompt,node_model_canvas,node_adr,node_traceability,node_final_proposal toneRose
```

## Components

### Case Evidence

Governing scenario, timeline, and authority constraints.

- [Challenge brief](https://github.com/abhibarman/fde-aviation/blob/main/case-study/00_challenge_brief.md): case document · `case-study/00_challenge_brief.md`
- [Incident timeline](https://github.com/abhibarman/fde-aviation/blob/main/case-study/02_incident_timeline.md): case document · `case-study/02_incident_timeline.md`
- [Constraints & authorities](https://github.com/abhibarman/fde-aviation/blob/main/case-study/05_constraints_and_authorities.md): safety boundary · Defines decisions reserved for humans or authorized systems. · `case-study/05_constraints_and_authorities.md`
- [Challenge rules](https://github.com/abhibarman/fde-aviation/blob/main/README.md): scope rules · Excludes automated regulated aviation decisions. · `README.md`

### Operational Evidence

Synthetic file-based source extracts and neutral definitions.

- [Flight & gate records](https://github.com/abhibarman/fde-aviation/blob/main/data/raw/flights.csv): CSV extracts · `data/raw/flights.csv`
- [Disruption & message feeds](https://github.com/abhibarman/fde-aviation/blob/main/data/raw/disruption_events.jsonl): JSONL extracts · `data/raw/disruption_events.jsonl`
- [Passenger, crew & maintenance](https://github.com/abhibarman/fde-aviation/blob/main/data/raw/passenger_connections.csv): CSV extracts · `data/raw/passenger_connections.csv`
- [Data dictionary](https://github.com/abhibarman/fde-aviation/blob/main/data/reference/data_dictionary.csv): reference definitions · Neutral field and file descriptions. · `data/reference/data_dictionary.csv`

### AeroNexus Application

Provenance-aware interpretation, domain views, and presentation.

- [Evidence interpretation](https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/evidence.py): provenance layer · Preserves sources, contradictions, and finding status. · `aeronexus/evidence.py`
- [Operational ontology](https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/ontology.py): domain model · Builds operational domain views from interpreted evidence. · `aeronexus/ontology.py`
- [Application composition](https://github.com/abhibarman/fde-aviation/blob/main/aeronexus/main.py): package entry point · `aeronexus/main.py`
- [Streamlit UI](https://github.com/abhibarman/fde-aviation/blob/main/streamlit_app.py): interactive runtime · Presentation boundary for investigation outputs. · `streamlit_app.py`

### Participant Delivery

Structured investigation and proposal artifacts.

- [Discovery guidance](https://github.com/abhibarman/fde-aviation/blob/main/participant-prompts/01_discovery.md): participant instruction · `participant-prompts/01_discovery.md`
- [Application guidance](https://github.com/abhibarman/fde-aviation/blob/main/participant-prompts/06_application.md): participant instruction · `participant-prompts/06_application.md`
- [Bounded-context canvas](https://github.com/abhibarman/fde-aviation/blob/main/templates/05_bounded_context_canvas.md): deliverable template · `templates/05_bounded_context_canvas.md`
- [Architecture decisions](https://github.com/abhibarman/fde-aviation/blob/main/templates/10_adr.md): ADR template · `templates/10_adr.md`
- [Traceability record](https://github.com/abhibarman/fde-aviation/blob/main/templates/11_traceability.csv): CSV template · Links facts, derivations, hypotheses, and open questions to evidence. · `templates/11_traceability.csv`
- [Final proposal](https://github.com/abhibarman/fde-aviation/blob/main/participant-outputs/08_final_proposal.md): participant output · `participant-outputs/08_final_proposal.md`

## Connections

- Challenge brief → Discovery guidance: frames investigation
- Incident timeline → Evidence interpretation: case evidence
- Constraints & authorities → Operational ontology: constrains proposals
- Challenge rules → Streamlit UI: limits decision support
- Flight & gate records → Evidence interpretation: source records
- Disruption & message feeds → Evidence interpretation: event evidence
- Passenger, crew & maintenance → Evidence interpretation: dependency evidence
- Data dictionary → Evidence interpretation: interprets fields
- Evidence interpretation → Operational ontology: provenance-aware findings
- Operational ontology → Application composition: domain views
- Application composition → Streamlit UI: powers UI
- Discovery guidance → Bounded-context canvas: guides modeling
- Application guidance → Architecture decisions: guides architecture
- Evidence interpretation → Traceability record: sources findings
- Bounded-context canvas → Traceability record: records boundaries
- Architecture decisions → Traceability record: records choices
- Traceability record → Final proposal: evidence-backed proposal
- Constraints & authorities → Final proposal: safety scope