# athinakantis/full-stack-countries-app architecture

> Architecture diagram of the GitHub repository athinakantis/full-stack-countries-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/athinakantis/full-stack-countries-app
- Repository: https://github.com/athinakantis/full-stack-countries-app

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    User["User"]:::external --> Browser["Browser (SPA)"]:::frontend

    %% CDN and Hosting
    Browser --> CDN["Netlify CDN"]:::frontend
    CDN --> StaticAssets["Static Assets (public)"]:::frontend

    %% Frontend Application
    Browser --> ReactSPA["React SPA"]:::frontend

    subgraph "Frontend"
        direction TB
        ReactSPA --> Main["main.tsx"]:::frontend
        Main --> AppComp["App.tsx"]:::frontend
        AppComp --> SupabaseConfig["supabase.ts"]:::frontend
        AppComp --> API_Layer["API Layer"]:::frontend
        AppComp --> UI_Layer["UI Components"]:::frontend
        AppComp --> StateTheme["State & Theme"]:::frontend

        subgraph "API Layer"
            direction TB
            Axios["axios.ts"]:::frontend
            CountriesSvc["countries.ts"]:::frontend
            FavoritesSvc["favorites.ts"]:::frontend
            WeatherSvc["weather.ts"]:::frontend
            TestSvc["test.ts"]:::frontend
            API_Layer --> Axios
            Axios --> CountriesSvc
            Axios --> FavoritesSvc
            Axios --> WeatherSvc
            Axios --> TestSvc
        end

        subgraph "UI Components"
            direction TB
            Login["Login.tsx"]:::frontend
            AuthRedirect["AuthRedirect.tsx"]:::frontend
            ProtectedRoute["ProtectedRoute.tsx"]:::frontend
            CountriesList["CountriesList.tsx"]:::frontend
            CountryCard["CountryCard.tsx"]:::frontend
            CountryDetail["CountryDetail.tsx"]:::frontend
            FavoriteButton["FavoriteButton.tsx"]:::frontend
            FavoritesView["Favorite.tsx"]:::frontend
            WeatherInfo["WeatherInfo.tsx"]:::frontend
            UI_Layer --> Login
            UI_Layer --> AuthRedirect
            UI_Layer --> ProtectedRoute
            UI_Layer --> CountriesList
            UI_Layer --> CountryCard
            UI_Layer --> CountryDetail
            UI_Layer --> FavoriteButton
            UI_Layer --> FavoritesView
            UI_Layer --> WeatherInfo
        end

        subgraph "State & Theme"
            direction TB
            AuthContext["AuthContext.tsx"]:::frontend
            SearchContext["SearchContext.tsx"]:::frontend
            ReduxStore["store.ts"]:::frontend
            ThemeProvider["ThemeProvider.tsx"]:::frontend
            StateTheme --> AuthContext
            StateTheme --> SearchContext
            StateTheme --> ReduxStore
            StateTheme --> ThemeProvider
        end
    end

    %% Backend Application
    subgraph "Backend"
        direction TB
        NestMain["main.ts"]:::backend
        NestMain --> AppModule["app.module.ts"]:::backend

        subgraph "Controllers"
            direction TB
            AppController["app.controller.ts"]:::backend
            TestController["test.controller.ts"]:::backend
        end

        subgraph "Services"
            direction TB
            AppService["app.service.ts"]:::backend
            SupabaseService["supabase.service.ts"]:::backend
        end

        AppModule --> AppController
        AppModule --> TestController
        AppModule --> AppService
        AppModule --> SupabaseService
    end

    %% API Interaction
    API_Layer -->|"REST Calls"| NestMain
    NestMain -->|"Handles Requests"| AppController
    AppController --> AppService
    AppService --> SupabaseService
    SupabaseService --> SupabaseDB["Supabase (Auth & Postgres)"]:::db

    %% External Services
    subgraph "External Services"
        direction TB
        WeatherAPI["Weather API"]:::external
        MapsAPI["Google Maps API"]:::external
    end
    WeatherSvc -->|Fetch Weather| WeatherAPI
    CountryDetail -->|Load Map| MapsAPI

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GH_Actions["GitHub Actions"]:::ci
        CypressRunner["Cypress Runner"]:::ci
        GH_Actions --> CypressRunner
        CypressRunner --> Browser
    end

    %% Click Events
    click ReactSPA "https://github.com/athinakantis/full-stack-countries-app/tree/starter/frontend/src"
    click Main "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/main.tsx"
    click AppComp "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/App.tsx"
    click SupabaseConfig "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/config/supabase.ts"
    click Axios "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/api/axios.ts"
    click CountriesSvc "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/api/services/countries.ts"
    click FavoritesSvc "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/api/services/favorites.ts"
    click WeatherSvc "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/api/services/weather.ts"
    click TestSvc "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/api/services/test.ts"
    click Login "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/Auth/Login.tsx"
    click AuthRedirect "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/Auth/AuthRedirect.tsx"
    click ProtectedRoute "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/Auth/ProtectedRoute.tsx"
    click CountriesList "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/CountriesList.tsx"
    click CountryCard "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/CountryCard.tsx"
    click CountryDetail "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/CountryDetail.tsx"
    click FavoriteButton "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/FavoriteButton.tsx"
    click FavoritesView "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/Favorite.tsx"
    click WeatherInfo "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/components/WeatherInfo.tsx"
    click AuthContext "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/context/AuthContext.tsx"
    click SearchContext "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/context/SearchContext.tsx"
    click ReduxStore "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/store/store.ts"
    click ThemeProvider "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/src/theme/ThemeProvider.tsx"
    click NestMain "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/main.ts"
    click AppModule "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/app.module.ts"
    click AppController "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/controllers/app.controller.ts"
    click TestController "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/controllers/test.controller.ts"
    click AppService "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/services/app.service.ts"
    click SupabaseService "https://github.com/athinakantis/full-stack-countries-app/blob/starter/backend/src/services/supabase.service.ts"
    click StaticAssets "https://github.com/athinakantis/full-stack-countries-app/tree/starter/frontend/public"
    click CDN "https://github.com/athinakantis/full-stack-countries-app/tree/starter/frontend/public/_redirects"
    click GH_Actions "https://github.com/athinakantis/full-stack-countries-app/blob/starter/.github/workflows/main.yml"
    click CypressRunner "https://github.com/athinakantis/full-stack-countries-app/blob/starter/frontend/cypress.config.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#E6FFED,stroke:#22863a,stroke-width:1px
    classDef db fill:#FFEFD5,stroke:#d2691e,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#6a737d,stroke-width:1px
    classDef ci fill:#F3E5F5,stroke:#6f42c1,stroke-width:1px
```
