# oopsiepoopsie/chonker-finder architecture

> Architecture diagram of the GitHub repository oopsiepoopsie/chonker-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oopsiepoopsie/chonker-finder
- Repository: https://github.com/oopsiepoopsie/chonker-finder

## Overview

##### Project type and purpose
- The frontend is a React+TypeScript single-page app built with Vite. The backend is a Flask-based Python API server using SQLite for persistence. The whole system is containerized via Docker and orchestrated with docker-compose.

##### File structure
- Top-level:
- docker-compose.yml (defines two services: backend & frontend)
- backend/ (Flask API, DB initialization, uploads dir, requirements.txt, Dockerfile)
- frontend/ (React UI, TypeScript config, Vite, Dockerfile)
- troubleshooting/ (guides for port forwarding)
- backend/:
- server.py (Flask app exposing REST endpoints)
- create_db/ (scripts to create & seed SQLite tables)
- instance/db_chonker.db (SQLite database file)
- uploads/ (static file storage for user uploads)
- Docker config (.dockerignore, Dockerfile)
- frontend/:
- src/ (App.tsx, map & UI components, config, data lib)
- public/index.html
- tailwind & ESLint configs
- Docker config
- package.json (dependencies)
- docker-compose.yml ties both containers onto a common network and binds ports.

##### README for additional insights
- Confirms Flask + SQLite on the backend.
- Confirms React + Vite + TypeScript on the frontend.
- No explicit mention of external services, but map.ts and marker-clusterer.ts suggest use of a mapping API (Leaflet/Google Maps/Mapbox).

##### Main components & interactions
a. Components:
- Client Browser (SPA)
- Frontend Container (React + Vite)
- Backend Container (Flask API)
- SQLite Database (within backend container or mounted volume)
- File Storage (uploads directory)
- External Mapping Service (e.g., Leaflet tiles or Google Maps API)
b. Interactions:
1. User → Browser loads SPA from Frontend Container.
2. SPA → Backend API calls (HTTP) to Flask endpoints (e.g., GET /chonkers, POST /upload).
3. Flask → SQLite read/write via SQLAlchemy or sqlite3.
4. Flask → serves static files from /uploads on disk.
5. SPA → External Mapping Service for map tiles & geocoding.
6. docker-compose network links frontend & backend.
c. Architectural patterns & principles:
- Clear separation of concerns: UI vs API vs data store.
- Containerization: both services isolated in Docker.
- Simple monolithic backend (Flask + SQLite) with possible horizontal scale via multiple containers in the future.
- SPA consumes RESTful API.
d. Key technologies/frameworks:
- Frontend: React, TypeScript, Vite, Tailwind CSS, ESLint
- Backend: Python, Flask, SQLite
- DevOps: Docker, docker-compose

##### Detailed breakdown
- Flask server process
- Mounted volume: /instance/db_chonker.db (SQLite)
- Mounted volume: /uploads (static files)
- Ports:
- Frontend: 5173 (Vite default) → Host port
- Backend: 5000 (Flask) → Host port

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User Browser"]:::external

    %% Docker Compose Orchestration
    subgraph "Docker Compose"
        direction TB
        Compose["docker-compose.yml"]:::orchestration
        click Compose "https://github.com/oopsiepoopsie/chonker-finder/blob/main/docker-compose.yml"

        %% Frontend Service
        subgraph "Frontend Container"
            direction TB
            FC["Frontend Container"]:::frontend
            click FC "https://github.com/oopsiepoopsie/chonker-finder/tree/main/frontend/"

            %% SPA Entry
            MainTSX["main.tsx"]:::frontend
            click MainTSX "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/src/main.tsx"
            IndexHTML["index.html"]:::frontend
            click IndexHTML "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/index.html"

            %% UI Components
            UI["React UI Components"]:::frontend
            click UI "https://github.com/oopsiepoopsie/chonker-finder/tree/main/frontend/src/ui/"

            %% Map Config
            MapTS["map.ts"]:::frontend
            click MapTS "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/src/config/map.ts"
            ClusterTS["marker-clusterer.ts"]:::frontend
            click ClusterTS "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/src/config/marker-clusterer.ts"

            %% Data & Library
            ChonkersJSON["chonkers.json"]:::frontend
            click ChonkersJSON "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/src/data/chonkers.json"
            LibTS["chonkers.ts"]:::frontend
            click LibTS "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/src/lib/chonkers.ts"

            %% Build & Tooling
            ViteConfig["vite.config.ts"]:::frontend
            click ViteConfig "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/vite.config.ts"
            TSConfig["tsconfig.json"]:::frontend
            click TSConfig "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/tsconfig.json"
            TailwindConfig["tailwind.config.ts"]:::frontend
            click TailwindConfig "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/tailwind.config.ts"
            ESLintConfig["eslint.config.js"]:::frontend
            click ESLintConfig "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/eslint.config.js"
            PostCSSConfig["postcss.config.js"]:::frontend
            click PostCSSConfig "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/postcss.config.js"
        end

        %% Backend Service
        subgraph "Backend Container"
            direction TB
            BC["Backend Container"]:::backend
            click BC "https://github.com/oopsiepoopsie/chonker-finder/tree/main/backend/"

            API["Flask API Server"]:::backend
            click API "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/server.py"

            %% Database Init Scripts
            subgraph "DB Init Scripts"
                direction TB
                CreateTable["create_table.py"]:::backend
                click CreateTable "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/create_db/create_table.py"
                SeedTable["seed_table.py"]:::backend
                click SeedTable "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/create_db/seed_table.py"
            end

            DBFile["db_chonker.db"]:::datastore
            click DBFile "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/instance/db_chonker.db"

            Uploads["Uploads Directory"]:::datastore
            click Uploads "https://github.com/oopsiepoopsie/chonker-finder/tree/main/backend/uploads/"

            DockerfileB["Dockerfile"]:::backend
            click DockerfileB "https://github.com/oopsiepoopsie/chonker-finder/tree/main/backend/Dockerfile"
            DockerIgnore[".dockerignore"]:::backend
            click DockerIgnore "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/.dockerignore"
        end

        %% Troubleshooting & Docs
        Troubleshoot["Port Forwarding Guide"]:::documentation
        click Troubleshoot "https://github.com/oopsiepoopsie/chonker-finder/blob/main/troubleshooting/docker-port-forwarding.md"
        READMEAll["Documentation"]:::documentation
        click READMEAll "https://github.com/oopsiepoopsie/chonker-finder/blob/main/README.md"
        click READMEAll "https://github.com/oopsiepoopsie/chonker-finder/blob/main/backend/README.md"
        click READMEAll "https://github.com/oopsiepoopsie/chonker-finder/blob/main/frontend/README.md"
    end

    %% External Mapping Service
    MapService["External Mapping Service"]:::external

    %% Connections
    User -->|"loads SPA"| FC
    FC -->|"HTTP/REST 5173"| API
    API -->|"reads/writes SQL"| DBFile
    API -->|"serves static files"| Uploads
    FC -->|"fetch map tiles"| MapService
    FC -->|"Docker network"| API
    Compose --> FC
    Compose --> BC

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#00aa00,stroke-width:1px;
    classDef backend fill:#e0f0ff,stroke:#0055aa,stroke-width:1px;
    classDef datastore fill:#fff4e5,stroke:#ff8800,stroke-width:1px;
    classDef orchestration fill:#f0f0f0,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#f5e6ff,stroke:#aa00aa,stroke-width:1px;
    classDef documentation fill:#ffffe0,stroke:#aaaa00,stroke-width:1px;
```
