# poiixen/senior_design architecture

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

- Interactive diagram: https://gitdiagram.com/poiixen/senior_design
- Repository: https://github.com/poiixen/senior_design

## Overview

Team Science ingests tabular datasets, validates and profiles them, runs quality diagnostics and column comparisons, then persists report summaries for retrieval through an API and React dashboard. The graph preserves the documented upload-to-report workflow and major analysis capabilities. Some wiring is supported only by the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`backend/services/analysis_service.py`](https://github.com/poiixen/senior_design/blob/main/backend/services/analysis_service.py) (Analysis service), [`backend/api/main.py`](https://github.com/poiixen/senior_design/blob/main/backend/api/main.py) (Analysis API), [`frontend/app/lib/api.ts`](https://github.com/poiixen/senior_design/blob/main/frontend/app/lib/api.ts) (API client), [`backend/database/repository.py`](https://github.com/poiixen/senior_design/blob/main/backend/database/repository.py) (Persistence repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Dataset ingestion"]
  node_csv["CSV loader<br/>[csv_loader.py]"]
  node_adapter["Dataset adapter<br/>[adult_adapter.py]"]
  node_dataset_loader["Dataset loader<br/>[dataset_loader.py]"]
end

subgraph group_analysis["Analysis and comparisons"]
  node_analysis_service["Analysis service"]
  node_validation["Dataset validation"]
  node_profiler["Dataset profiler"]
  node_missing["Missing values"]
  node_duplicates["Duplicate detection"]
  node_outliers["Outlier detection"]
  node_column_quality["Column quality"]
  node_correlation["Correlation analysis"]
  node_categorical["Categorical comparison"]
  node_numeric["Numeric group comparison"]
  node_comparison_common["Comparison utilities"]
end

subgraph group_backend["API and persistence"]
  node_api["Analysis API<br/>[main.py]"]
  node_database[("Metadata database<br/>[records.py]")]
  node_repository["Persistence repository<br/>[repository.py]"]
  node_connection["Database sessions<br/>[connection.py]"]
  node_dataset_store[("Parsed dataset store<br/>[dataset_store.py]")]
end

subgraph group_frontend["Dashboard"]
  node_home["Upload page<br/>[home.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_report_api["Report schema<br/>[report.ts]"]
  node_report_page["Report dashboard<br/>[report.tsx]"]
  node_reports_page["Report list<br/>[reports.tsx]"]
  node_docs_page["Documentation page<br/>[documentation.tsx]"]
end

subgraph group_identity["User accounts"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_auth_service["Credential service<br/>[auth_service.py]"]
end

node_uploader(("Dataset uploader"))

node_uploader -->|"provides CSV"| node_csv
node_csv -->|"loads data"| node_dataset_loader
node_adapter -->|"normalizes data"| node_dataset_loader
node_home -->|"submits upload"| node_client
node_client -->|"posts analysis"| node_api
node_api -->|"parses upload"| node_dataset_loader
node_api -->|"runs analysis"| node_analysis_service
node_analysis_service -->|"validates dataset"| node_validation
node_analysis_service -->|"profiles columns"| node_profiler
node_analysis_service -->|"compares categories"| node_categorical
node_analysis_service -->|"compares groups"| node_numeric
node_analysis_service -->|"calculates correlation"| node_correlation
node_profiler -->|"detects missingness"| node_missing
node_profiler -->|"detects duplicates"| node_duplicates
node_categorical -->|"uses utilities"| node_comparison_common
node_numeric -->|"uses utilities"| node_comparison_common
node_analysis_service -->|"saves findings"| node_repository
node_analysis_service -->|"stores parsed rows"| node_dataset_store
node_repository -->|"persists metadata"| node_database
node_connection -->|"creates sessions"| node_database
node_api -->|"reads reports"| node_repository
node_api -->|"opens transactions"| node_connection
node_api -->|"returns report"| node_report_page
node_client -->|"uses report schema"| node_report_api
node_report_page -->|"fetches report"| node_client
node_reports_page -->|"fetches reports"| node_client
node_api -->|"checks identity"| node_auth_api
node_auth_api -->|"authenticates users"| node_auth_service
node_auth_api -->|"loads accounts"| node_repository
node_auth_service -->|"looks up users"| node_repository

click node_csv "https://github.com/poiixen/senior_design/blob/main/backend/ingestion/csv_loader.py"
click node_adapter "https://github.com/poiixen/senior_design/blob/main/backend/ingestion/adult_adapter.py"
click node_dataset_loader "https://github.com/poiixen/senior_design/blob/main/backend/ingestion/dataset_loader.py"
click node_api "https://github.com/poiixen/senior_design/blob/main/backend/api/main.py"
click node_analysis_service "https://github.com/poiixen/senior_design/blob/main/backend/services/analysis_service.py"
click node_validation "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/validate_dataset.py"
click node_profiler "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/generic_dataset_profiler.py"
click node_missing "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/missing_value_detection.py"
click node_duplicates "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/duplicate_detection.py"
click node_outliers "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/iqr_outlier_detection.py"
click node_column_quality "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/column_quality_detection.py"
click node_correlation "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/correlation_analysis.py"
click node_categorical "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/categorical_comparison.py"
click node_numeric "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/numeric_group_comparison.py"
click node_comparison_common "https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/comparison_common.py"
click node_database "https://github.com/poiixen/senior_design/blob/main/backend/models/records.py"
click node_repository "https://github.com/poiixen/senior_design/blob/main/backend/database/repository.py"
click node_connection "https://github.com/poiixen/senior_design/blob/main/backend/database/connection.py"
click node_dataset_store "https://github.com/poiixen/senior_design/blob/main/backend/database/dataset_store.py"
click node_auth_api "https://github.com/poiixen/senior_design/blob/main/backend/api/auth.py"
click node_auth_service "https://github.com/poiixen/senior_design/blob/main/backend/services/auth_service.py"
click node_home "https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/home.tsx"
click node_client "https://github.com/poiixen/senior_design/blob/main/frontend/app/lib/api.ts"
click node_report_api "https://github.com/poiixen/senior_design/blob/main/frontend/app/lib/report.ts"
click node_report_page "https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/report.tsx"
click node_reports_page "https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/reports.tsx"
click node_docs_page "https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/documentation.tsx"

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_csv,node_adapter,node_dataset_loader toneBlue
class node_analysis_service,node_validation,node_profiler,node_missing,node_duplicates,node_outliers,node_column_quality,node_correlation,node_categorical,node_numeric,node_comparison_common toneAmber
class node_api,node_database,node_repository,node_connection,node_dataset_store toneMint
class node_home,node_client,node_report_api,node_report_page,node_reports_page,node_docs_page toneRose
class node_auth_api,node_auth_service,node_uploader toneIndigo
```

## Components

### Dataset ingestion

- [CSV loader](https://github.com/poiixen/senior_design/blob/main/backend/ingestion/csv_loader.py): `backend/ingestion/csv_loader.py`
- [Dataset adapter](https://github.com/poiixen/senior_design/blob/main/backend/ingestion/adult_adapter.py): `backend/ingestion/adult_adapter.py`
- [Dataset loader](https://github.com/poiixen/senior_design/blob/main/backend/ingestion/dataset_loader.py): `backend/ingestion/dataset_loader.py`

### Analysis and comparisons

- [Analysis service](https://github.com/poiixen/senior_design/blob/main/backend/services/analysis_service.py): `backend/services/analysis_service.py`
- [Dataset validation](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/validate_dataset.py): `backend/diagnostics/validate_dataset.py`
- [Dataset profiler](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/generic_dataset_profiler.py): `backend/diagnostics/generic_dataset_profiler.py`
- [Missing values](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/missing_value_detection.py): `backend/diagnostics/missing_value_detection.py`
- [Duplicate detection](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/duplicate_detection.py): `backend/diagnostics/duplicate_detection.py`
- [Outlier detection](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/iqr_outlier_detection.py): `backend/diagnostics/iqr_outlier_detection.py`
- [Column quality](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/column_quality_detection.py): `backend/diagnostics/column_quality_detection.py`
- [Correlation analysis](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/correlation_analysis.py): `backend/diagnostics/correlation_analysis.py`
- [Categorical comparison](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/categorical_comparison.py): `backend/diagnostics/categorical_comparison.py`
- [Numeric group comparison](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/numeric_group_comparison.py): `backend/diagnostics/numeric_group_comparison.py`
- [Comparison utilities](https://github.com/poiixen/senior_design/blob/main/backend/diagnostics/comparison_common.py): `backend/diagnostics/comparison_common.py`

### API and persistence

- [Analysis API](https://github.com/poiixen/senior_design/blob/main/backend/api/main.py): `backend/api/main.py`
- [Metadata database](https://github.com/poiixen/senior_design/blob/main/backend/models/records.py): `backend/models/records.py`
- [Persistence repository](https://github.com/poiixen/senior_design/blob/main/backend/database/repository.py): `backend/database/repository.py`
- [Database sessions](https://github.com/poiixen/senior_design/blob/main/backend/database/connection.py): `backend/database/connection.py`
- [Parsed dataset store](https://github.com/poiixen/senior_design/blob/main/backend/database/dataset_store.py): `backend/database/dataset_store.py`

### Dashboard

- [Upload page](https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/home.tsx): `frontend/app/routes/home.tsx`
- [API client](https://github.com/poiixen/senior_design/blob/main/frontend/app/lib/api.ts): `frontend/app/lib/api.ts`
- [Report schema](https://github.com/poiixen/senior_design/blob/main/frontend/app/lib/report.ts): `frontend/app/lib/report.ts`
- [Report dashboard](https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/report.tsx): `frontend/app/routes/report.tsx`
- [Report list](https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/reports.tsx): `frontend/app/routes/reports.tsx`
- [Documentation page](https://github.com/poiixen/senior_design/blob/main/frontend/app/routes/documentation.tsx): `frontend/app/routes/documentation.tsx`

### User accounts

- [Authentication API](https://github.com/poiixen/senior_design/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Credential service](https://github.com/poiixen/senior_design/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`

### Other components

- **Dataset uploader**

## Connections

- Dataset uploader → CSV loader: provides CSV
- CSV loader → Dataset loader: loads data (evidence: `backend/ingestion/dataset_loader.py`)
- Dataset adapter → Dataset loader: normalizes data
- Upload page → API client: submits upload
- API client → Analysis API: posts analysis
- Analysis API → Dataset loader: parses upload (evidence: `backend/api/main.py`)
- Analysis API → Analysis service: runs analysis (evidence: `backend/api/main.py`)
- Analysis service → Dataset validation: validates dataset (evidence: `backend/services/analysis_service.py`)
- Analysis service → Dataset profiler: profiles columns (evidence: `backend/services/analysis_service.py`)
- Analysis service → Categorical comparison: compares categories (evidence: `backend/services/analysis_service.py`)
- Analysis service → Numeric group comparison: compares groups (evidence: `backend/services/analysis_service.py`)
- Analysis service → Correlation analysis: calculates correlation (evidence: `backend/services/analysis_service.py`)
- Dataset profiler → Missing values: detects missingness (evidence: `backend/diagnostics/generic_dataset_profiler.py`)
- Dataset profiler → Duplicate detection: detects duplicates (evidence: `backend/diagnostics/generic_dataset_profiler.py`)
- Categorical comparison → Comparison utilities: uses utilities (evidence: `backend/diagnostics/categorical_comparison.py`)
- Numeric group comparison → Comparison utilities: uses utilities (evidence: `backend/diagnostics/numeric_group_comparison.py`)
- Analysis service → Persistence repository: saves findings (evidence: `backend/services/analysis_service.py`)
- Analysis service → Parsed dataset store: stores parsed rows (evidence: `backend/services/analysis_service.py`)
- Persistence repository → Metadata database: persists metadata (evidence: `backend/database/repository.py`)
- Database sessions → Metadata database: creates sessions (evidence: `backend/database/connection.py`)
- Analysis API → Persistence repository: reads reports (evidence: `backend/api/main.py`)
- Analysis API → Database sessions: opens transactions (evidence: `backend/api/main.py`)
- Analysis API → Report dashboard: returns report
- API client → Report schema: uses report schema (evidence: `frontend/app/lib/api.ts`)
- Report dashboard → API client: fetches report
- Report list → API client: fetches reports
- Analysis API → Authentication API: checks identity (evidence: `backend/api/main.py`)
- Authentication API → Credential service: authenticates users (evidence: `backend/api/auth.py`)
- Authentication API → Persistence repository: loads accounts (evidence: `backend/api/auth.py`)
- Credential service → Persistence repository: looks up users (evidence: `backend/services/auth_service.py`)