The frontend is a single-page application (SPA) built with React and TypeScript. Its architecture follows a modular, feature-based structure, designed to maximize maintainability, scalability, and developer efficiency.

Key Principles

• Component-Based: UI functionality is broken into small, reusable components organized by domain (e.g., buttons, map layers, data logic).
• Separation of Concerns: Responsibilities are clearly divided between presentation (views/components), data (API, data files), and logic (state, interactions).
• API-Centric Communication: All backend communication is handled through REST APIs, abstracted into dedicated modules under src/api/.
• Collocated Assets: Each component lives alongside its .css and .test.tsx files, promoting local cohesion and easier maintenance.
• Performance-First: Built with Vite for lightning-fast development and optimized builds.

Project Structure

The src/Components directory is structured by purpose:

• views/: Top-level screens that define the core user flow (e.g., WorldMap)
• components/: Shared UI elements like buttons and selectors
• layers/: Map rendering layers (countries, base maps)
• data/: Static world country data
• api/: Encapsulated logic for communicating with backend services

This structure ensures high clarity for new developers onboarding into the codebase, while supporting rapid iteration and scalability.