How oopsiepoopsie/chonker-finder works
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