# juliancumps/bristol-predict architecture

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

- Interactive diagram: https://gitdiagram.com/juliancumps/bristol-predict
- Repository: https://github.com/juliancumps/bristol-predict

## Overview

##### Project Type and Purpose
- This is a full-stack interactive display for Bristol Bay salmon runs.
- Front-end: React + Vite + Mapbox GL JS for map visualization and time-series controls.
- Backend: Node.js/Express scrapers + API server (currently in development).
- Storage: SQL database (planned PostgreSQL).
- External services: ADF&G data, Port Moller fishery data, weather APIs, Mapbox.

##### Main Components
a. Front-end UI
- React app (src/)
- Mapbox map component, time slider, sidebar
- Build & bundling: Vite (vite.config.js)
b. Backend API & Scrapers
- Express server (backend/src/server.js)
- Data scrapers (backend/src/scrapers/harvestScraper.js)
- DB interface & schema (backend/src/db/schema.sql)
c. Database
- PostgreSQL (future) implementing schema.sql
d. External Data Sources
- Alaska Dept. Fish & Game API
- Port Moller test fishery data
- Weather service APIs
- Mapbox (tile & style service)

##### Relationships & Data Flow
1. End-user interacts with React UI in browser.
2. UI makes HTTP(S) requests to Node/Express API for data (raw counts, time series).
3. Express server invokes scrapers (manual or scheduled) to fetch external data, writes into SQL DB.
4. API endpoints query the DB, return JSON to the UI.
5. UI renders map tiles via Mapbox GL JS (direct browser→Mapbox CDN).

##### Important Architectural Patterns
- Separation of concerns: UI vs. API vs. Data layer
- Modular scrapers: Each scraper module encapsulates one external source
- Future extensibility: ML pipeline can read/write same DB, expose prediction endpoints

##### Technologies & Frameworks
- Front-end: React, Vite, Mapbox GL JS
- Backend: Node.js, Express
- Database: PostgreSQL (planned)
- Scheduling: cron/job runner (future)
- Deployment: Docker containers or managed cloud (future)

##### Final Checklist
- All major components (UI, API, DB, external).
- Notes on config (.env keys), build tools (Vite/Node), and technologies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Client Layer
    subgraph "Browser/Client"
        direction TB
        ReactApp["React App"]:::frontend
        mainjsx["main.jsx"]:::frontend
        Appjsx["App.jsx"]:::frontend
        BristolBayMap["BristolBayMap.jsx"]:::frontend
        TimeSlider["TimeSlider.jsx"]:::frontend
        DistrictSidebar["DistrictSidebar.jsx"]:::frontend
        StaticAssets["Static Assets (public/)"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
        EnvFrontend[".env (VITE_MAPBOX_TOKEN)"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server"
        direction TB
        ExpressAPI["Express API Server"]:::backend
        Scraper["harvestScraper.js"]:::backend
        SchemaSQL["schema.sql"]:::backend
        EnvBackend[".env"]:::backend
        BackendPkg["package.json & lock"]:::backend
    end

    %% Database Layer
    PostgreSQL["PostgreSQL DB"]:::db

    %% ML Pipeline (Future)
    MLPipeline["ML Pipeline (future)"]:::backend

    %% External Services Layer
    subgraph "External Services"
        direction TB
        ADFG["ADF&G API"]:::external
        PortMoller["Port Moller Fishery Data"]:::external
        Weather["Weather Service APIs"]:::external
        Mapbox["Mapbox CDN & Styles"]:::external
    end

    %% Data Flows
    ReactApp -->|"GET /data?..."| ExpressAPI
    ReactApp -->|"map tile requests"| Mapbox
    ExpressAPI -->|"SQL queries"| PostgreSQL
    ExpressAPI -->|"harvestScraper calls"| ADFG
    ExpressAPI -->|"harvestScraper calls"| PortMoller
    ExpressAPI -->|"harvestScraper calls"| Weather
    PostgreSQL -->|"reads/writes"| MLPipeline
    MLPipeline -->|"writes predictions"| PostgreSQL

    %% Click Events
    click ReactApp "https://github.com/juliancumps/bristol-predict/tree/main//src"
    click mainjsx "https://github.com/juliancumps/bristol-predict/blob/main//src/main.jsx"
    click Appjsx "https://github.com/juliancumps/bristol-predict/blob/main//src/App.jsx"
    click BristolBayMap "https://github.com/juliancumps/bristol-predict/blob/main//src/components/BristolBayMap.jsx"
    click TimeSlider "https://github.com/juliancumps/bristol-predict/blob/main//src/components/TimeSlider.jsx"
    click DistrictSidebar "https://github.com/juliancumps/bristol-predict/blob/main//src/components/DistrictSidebar.jsx"
    click StaticAssets "https://github.com/juliancumps/bristol-predict/tree/main//public"
    click ViteConfig "https://github.com/juliancumps/bristol-predict/blob/main/vite.config.js"
    click EnvFrontend "https://github.com/juliancumps/bristol-predict/blob/main//.env"
    click ExpressAPI "https://github.com/juliancumps/bristol-predict/blob/main//backend/src/server.js"
    click Scraper "https://github.com/juliancumps/bristol-predict/blob/main//backend/src/scrapers/harvestScraper.js"
    click SchemaSQL "https://github.com/juliancumps/bristol-predict/blob/main//backend/src/db/schema.sql"
    click EnvBackend "https://github.com/juliancumps/bristol-predict/blob/main//backend/.env"
    click BackendPkg "https://github.com/juliancumps/bristol-predict/blob/main//backend/package.json"
    click FrontendPkg "https://github.com/juliancumps/bristol-predict/blob/main//package.json"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#036BC9,color:#000
    classDef backend fill:#C4FBCF,stroke:#2E8B57,color:#000
    classDef db fill:#FBE5AE,stroke:#D18F04,color:#000
    classDef external fill:#E2E2E2,stroke:#8F8F8F,color:#000
```
