# tuckerbrewer12/birdieeyeview architecture

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

- Interactive diagram: https://gitdiagram.com/tuckerbrewer12/birdieeyeview
- Repository: https://github.com/tuckerbrewer12/birdieeyeview

## Overview

BirdieEyeView is a golf scorecard capture and performance-tracking app. Its central workflow is to photograph a scorecard, review and correct extracted details, save a hole-by-hole round, then use accumulated rounds for analytics and improvement insights. The graph includes the documented OCR/LLM and goal capabilities, but some backend routes and extraction internals were not sampled; those links rely on the README. Optional report storage is shown separately.

Main entry points: [`api/main.py`](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/main.py) (API entry), [`services/scan_service.py`](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/scan_service.py) (Scan extraction), [`database/db_manager.py`](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/database/db_manager.py) (Data manager), [`analytics/stats.py`](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/stats.py) (Round analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App experience"]
  node_frontend["Web app<br/>[App.tsx]"]
  node_scan_ui["Scan review"]
  node_scan_client["Scan client<br/>[scanRepository.ts]"]
end

subgraph group_api["API workflows"]
  node_api_entry["API entry<br/>[main.py]"]
  node_scan_routes["Scan routes<br/>[scan.py]"]
  node_round_routes["Round routes<br/>[rounds.py]"]
  node_analytics_routes["Analytics routes<br/>[stats.py]"]
  node_insight_routes["AI insights<br/>[ai_insights.py]"]
  node_scan_service["Scan extraction<br/>[scan_service.py]"]
  node_auth_routes["Account access<br/>[auth.py]"]
  node_ai_service["AI analysis<br/>[ai_service.py]"]
end

subgraph group_domain["Golf data"]
  node_round_model["Round model<br/>[round.py]"]
  node_db_manager["Data manager<br/>[db_manager.py]"]
  node_repositories["Data repositories"]
  node_postgres[("PostgreSQL")]
end

subgraph group_insights["Analytics and insights"]
  node_stats["Round analytics<br/>[stats.py]"]
  node_handicap["Handicap<br/>[handicap.py]"]
  node_eligibility["Round eligibility<br/>[eligibility.py]"]
end

subgraph group_integrations["External services"]
  node_ocr["Scorecard OCR"]
  node_course_api["Course lookup"]
  node_mistral{{"Mistral"}}
  node_gemini{{"Gemini"}}
  node_report_store["Scan report storage"]
  node_object_store[("S3-compatible store")]
end

node_golfer(("Golfer"))

node_golfer -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_scan_ui
node_scan_ui -->|"saves through"| node_scan_client
node_scan_client -.->|"submits scan"| node_scan_routes
node_api_entry -->|"registers"| node_scan_routes
node_api_entry -->|"registers"| node_round_routes
node_api_entry -->|"registers"| node_analytics_routes
node_api_entry -->|"registers"| node_insight_routes
node_api_entry -->|"registers"| node_auth_routes
node_scan_routes -.->|"extracts with"| node_scan_service
node_scan_service -.->|"prefetches OCR"| node_ocr
node_ocr -.->|"calls"| node_mistral
node_scan_service -.->|"uses extraction"| node_gemini
node_scan_service -->|"looks up courses"| node_course_api
node_scan_service -->|"saves round"| node_db_manager
node_scan_service -.->|"builds round"| node_round_model
node_round_routes -.->|"reads and saves"| node_db_manager
node_db_manager -->|"delegates to"| node_repositories
node_repositories -.->|"queries"| node_postgres
node_analytics_routes -.->|"requests metrics"| node_stats
node_insight_routes -.->|"requests insights"| node_ai_service
node_ai_service -->|"uses analytics"| node_stats
node_ai_service -->|"loads data"| node_db_manager
node_stats -->|"filters rounds"| node_eligibility
node_stats -->|"uses handicap"| node_handicap
node_auth_routes -->|"uses accounts"| node_db_manager
node_api_entry -->|"configures optionally"| node_report_store
node_report_store -.->|"stores reports"| node_object_store

click node_frontend "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/App.tsx"
click node_scan_ui "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/pages/scan/useScanReviewViewModel.ts"
click node_scan_client "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/data/scanRepository.ts"
click node_api_entry "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/main.py"
click node_scan_routes "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/scan.py"
click node_round_routes "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/rounds.py"
click node_analytics_routes "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/stats.py"
click node_insight_routes "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/ai_insights.py"
click node_scan_service "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/scan_service.py"
click node_auth_routes "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/auth.py"
click node_ai_service "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/ai_service.py"
click node_round_model "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/models/round.py"
click node_db_manager "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/database/db_manager.py"
click node_repositories "https://github.com/tuckerbrewer12/birdieeyeview/tree/main/database/repositories"
click node_stats "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/stats.py"
click node_handicap "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/handicap.py"
click node_eligibility "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/eligibility.py"
click node_ocr "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/mistral_ocr_service.py"
click node_course_api "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/golfcourse_api_service.py"
click node_report_store "https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/scan_report_storage.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_frontend,node_scan_ui,node_scan_client toneBlue
class node_api_entry,node_scan_routes,node_round_routes,node_analytics_routes,node_insight_routes,node_scan_service,node_auth_routes,node_ai_service toneAmber
class node_round_model,node_db_manager,node_repositories,node_postgres toneMint
class node_stats,node_handicap,node_eligibility toneRose
class node_ocr,node_course_api,node_mistral,node_gemini,node_report_store,node_object_store,node_golfer toneIndigo
```

## Components

### App experience

- [Web app](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scan review](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/pages/scan/useScanReviewViewModel.ts): `frontend/src/pages/scan/useScanReviewViewModel.ts`
- [Scan client](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/frontend/src/data/scanRepository.ts): `frontend/src/data/scanRepository.ts`

### API workflows

- [API entry](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/main.py): `api/main.py`
- [Scan routes](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/scan.py): `api/routers/scan.py`
- [Round routes](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/rounds.py): `api/routers/rounds.py`
- [Analytics routes](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/stats.py): `api/routers/stats.py`
- [AI insights](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/ai_insights.py): `api/routers/ai_insights.py`
- [Scan extraction](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/scan_service.py): `services/scan_service.py`
- [Account access](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/api/routers/auth.py): `api/routers/auth.py`
- [AI analysis](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/ai_service.py): `services/ai_service.py`

### Golf data

- [Round model](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/models/round.py): `models/round.py`
- [Data manager](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/database/db_manager.py): `database/db_manager.py`
- [Data repositories](https://github.com/tuckerbrewer12/birdieeyeview/tree/main/database/repositories): `database/repositories`
- **PostgreSQL**

### Analytics and insights

- [Round analytics](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/stats.py): `analytics/stats.py`
- [Handicap](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/handicap.py): `analytics/handicap.py`
- [Round eligibility](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/analytics/eligibility.py): `analytics/eligibility.py`

### External services

- [Scorecard OCR](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/mistral_ocr_service.py): `services/mistral_ocr_service.py`
- [Course lookup](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/golfcourse_api_service.py): `services/golfcourse_api_service.py`
- **Mistral**
- **Gemini**
- [Scan report storage](https://github.com/tuckerbrewer12/birdieeyeview/blob/main/services/scan_report_storage.py): `services/scan_report_storage.py`
- **S3-compatible store**

### Other components

- **Golfer**

## Connections

- Golfer → Web app: uses
- Web app → Scan review: routes to (evidence: `frontend/src/App.tsx`)
- Scan review → Scan client: saves through (evidence: `frontend/src/pages/scan/useScanReviewViewModel.ts`)
- Scan client → Scan routes: submits scan
- API entry → Scan routes: registers (evidence: `api/main.py`)
- API entry → Round routes: registers (evidence: `api/main.py`)
- API entry → Analytics routes: registers (evidence: `api/main.py`)
- API entry → AI insights: registers (evidence: `api/main.py`)
- API entry → Account access: registers (evidence: `api/main.py`)
- Scan routes → Scan extraction: extracts with
- Scan extraction → Scorecard OCR: prefetches OCR
- Scorecard OCR → Mistral: calls
- Scan extraction → Gemini: uses extraction
- Scan extraction → Course lookup: looks up courses (evidence: `services/scan_service.py`)
- Scan extraction → Data manager: saves round (evidence: `services/scan_service.py`)
- Scan extraction → Round model: builds round
- Round routes → Data manager: reads and saves
- Data manager → Data repositories: delegates to (evidence: `database/db_manager.py`)
- Data repositories → PostgreSQL: queries
- Analytics routes → Round analytics: requests metrics
- AI insights → AI analysis: requests insights
- AI analysis → Round analytics: uses analytics (evidence: `services/ai_service.py`)
- AI analysis → Data manager: loads data (evidence: `services/ai_service.py`)
- Round analytics → Round eligibility: filters rounds (evidence: `analytics/stats.py`)
- Round analytics → Handicap: uses handicap (evidence: `analytics/stats.py`)
- Account access → Data manager: uses accounts (evidence: `api/routers/auth.py`)
- API entry → Scan report storage: configures optionally (evidence: `api/main.py`)
- Scan report storage → S3-compatible store: stores reports (evidence: `services/scan_report_storage.py`)
