How athinakantis/full-stack-countries-app works
Project type and purpose
• This is a full-stack web application (“Countries Full Stack App”) with:
– A React/Vite/Tailwind-powered SPA frontend
– A NestJS REST API backend
– Supabase for authentication, database (Postgres) and storage
– Third-party external services (Weather API, Google Maps API)
– E2E testing (Cypress) and CI (GitHub Actions)
• Purpose: allow users to browse countries, see details (maps, weather), search/filter, authenticate, and favorite items.
Top-level file-structure analysis
• frontend/ – React app with:
– src/api (Axios wrapper + per-resource service modules: countries, favorites, weather, test)
– src/components (UI, pages, Auth subfolder, theme, context and redux store slices)
– config (Supabase client initialization)
– theme, types, utils
– cypress/ (E2E tests + fixtures + support)
– vite.config.ts, tsconfig, public/_redirects for Netlify routing
• backend/ – NestJS server with:
– src/controllers (app.controller, test.controller)
– src/services (app.service, supabase.service)
– main.ts, module definitions
– jest and e2e test setup
• CI/CD: .github/workflows/main.yml runs Cypress against frontend on push.
• Docs: README.md, Setup-Instructions.md, Supabase-Setup-Instructions.md
Key architectural patterns and design principles
• Frontend:
– Component-based UI, context + Redux Toolkit for global state, service layer for API calls, protected routes for auth.
– Theme Context and Tailwind for styling, Vite for bundling.
• Backend:
– NestJS follows MVC (controllers ↔ services ↔ providers).
– supabase.service encapsulates all Supabase interactions.
– Test controller for health checks/e2e.
• Data flow: all client requests go to NestJS API, which in turn queries Supabase (or proxies to external APIs), then returns JSON responses.
Main components
a. Client / Browser – React SPA
b. CDN / Static hosting – Netlify serves index.html, JS/CSS
c. API Gateway / Web server – NestJS application running on Node (hosted wherever you deploy backend)
d. Auth & Database – Supabase (Postgres + Auth)
e. Third-party services – Weather API, Google Maps API
f. CI/CD pipeline – GitHub Actions job for Cypress tests
g. E2E Test Runner – Cypress executing tests against deployed frontend
Relationships & interactions
• User → Browser SPA → axios.ts → NestJS REST endpoints
• NestJS Controller → Service Layer → Supabase client (queries + auth JWT)
• For weather/maps: NestJS (or client directly, depending on implementation) calls external REST APIs using stored API keys
• On login/signup: SPA redirects via Supabase OAuth/JWT flow; tokens stored in context
• Favorites: SPA → API → Supabase table “country_favorites”
• CI flow: GitHub Actions checks out code → installs deps → builds frontend → runs Cypress (using env secrets) → reports status.
Essential elements to capture
• All high-level components, subcomponents, and external dependencies
• Data-flow directions (user events → API → DB → back to UI)
• Auth flow (login redirect, JWT storage, ProtectedRoute in React)
• CI pipeline stage connecting to tests and environment secrets