How ad3m3r5/scratch-map works
Project type and purpose
• This is a single‐service full‑stack web application called “Scratch‑Map” that lets users “scratch off” (mark) countries or regions they’ve traveled to.
• It uses Node.js/Express on the backend, Pug for server‑side templating, Lowdb as an embedded JSON database, and serves a client‑side SVG map with pan/zoom and pop‑up controls.
High‑level file‑structure analysis
• server.js: application entry point
• controllers/: request handlers for map logic
• routes/: Express routing layer (routes/index.js maps URLs to controllers)
• views/: Pug templates (layout, index, map view, error pages)
• public/: client assets (CSS, JS modules for SVG controls and view logic, images)
• utils/: helper modules (database init, global constants, country‑code JSON files)
• compose.yaml & Dockerfile: containerization and deployment config
• .github/workflows: CI/CD pipelines
Key architectural insights from README
• Tech stack: NodeJS + Express + Pug + Lowdb
• Core features: world + country/state maps, date stamps, photo links
• Client‑side dependencies: svg-pan-zoom-container, sweetalert2, validator
a. Client Browser
• UI Layer: HTML/Pug‑generated pages, CSS, client JS modules
• SVG Map component with pan/zoom and pop‑ups
b. Web Server (Node.js/Express)
• Route Layer (routes/index.js)
• Controller Layer (controllers/*.js)
• View Renderer (Pug templates)
c. Data Layer
• Lowdb JSON store (utils/database.js writes/reads scratch data)
• utils/codes/*.json (static country/state definitions)
d. Infrastructure & DevOps
• Docker container running Node app
• compose.yaml for multi‑container setup (if needed)
• GitHub Actions (build, test, push)
Relationships and interactions
• Client → Server: HTTP GET/POST requests (map page load, scratch event submissions)
• Server: routes → controllers → database → controllers → render Pug → HTML response
• Client: fetches rendered HTML + static assets → executes client JS to load SVG, handle user clicks, send AJAX to server
• Database: Lowdb JSON file resides on local filesystem within container
• External: optional photo‑album URLs validated by validator.js; maps pan/zoom via svg‑pan‑zoom
Architectural patterns & design principles
• MVC‑style separation: routes (Controller entry), controllers (business logic), views (templates)
• Single monolithic service (no microservices)
• Server‑rendered UI with progressive client enhancements (SVG controls, pop‑ups)
• Containerized for portability and consistency