# klubjagiellonski/pola-web architecture

> Architecture diagram of the GitHub repository klubjagiellonski/pola-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klubjagiellonski/pola-web
- Repository: https://github.com/klubjagiellonski/pola-web

## Overview

##### Project Context and Purpose
- The project is a React-based web interface built with Gatsby (as seen in the gatsby-config.js, gatsby-node.js, and use of Gatsby plugins). It serves as the frontend for the “Pola. Zabierz ją na zakupy” application.
- Its main purpose is to let users scan product barcodes to retrieve information about whether a product is produced by a local Polish company. It works in close cooperation with a separate backend (hosted on Heroku) that supplies Pola API data.

##### High-Level Architecture Components
- “Presentation Layer”: This includes all the UI components built using React and organized under src/pages, src/components, and other module-specific directories (e.g., src/business, src/friends, src/newsletter, src/search, src/posts, etc.). These represent various parts of the user interface such as business profiles, article pages, search functionality, and partner information.
- “Data / Content Layer”: The content folder (with markdown files, JSON, YAML, and images) holds the static content served by Gatsby. In addition, Gatsby’s built-in GraphQL layer acts as a bridge to query this content during build and at run-time through the GraphQL explorer.
- “State Management and Business Logic”: The use of Redux (or a similar flux pattern) is evident in the state directories (e.g., src/app/state, src/business/state, src/friends/state, etc.). This layer handles global state, API errors, and other business logic.
- “Integration with Backend Services”: Although the primary logic and rendering occur on the frontend, the application makes API calls to the Pola backend server. This is represented by services files in various modules (e.g., src/newsletter/services, src/search/services, src/posts/services) that encapsulate external API communication.
- “Deployment/CI/CD Infrastructure”: The existence of Dockerfile, docker-compose.yaml, and GitHub workflow configuration files (.github/workflows/ci.yaml) suggest that deployment and continuous integration are configured. This pipeline automatically deploys changes (e.g., to GitHub Pages for the frontend and uses Heroku for the Pola API).
- “Testing Infrastructure”: Directories like __mocks__, src/test, and Jest configuration files are responsible for unit and integration testing.

##### Key Architectural Patterns and Technologies
- Use of Gatsby as a static site generator, which implies a build-time data-fetch paradigm using GraphQL.
- React component-based design and a Redux-like state management pattern for handling UI state and business logic.
- Modular organization: The project is split into folders that represent specific features (e.g., business, posts, newsletter, materials, suppliers) demonstrating a layered and domain-driven design.
- CI/CD integration with GitHub Actions and deployment through Docker and GitHub Pages.
- Testing infrastructure using Jest and React Testing Library for component verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Browser"]:::frontend

    %% Frontend (Presentation Layer)
    subgraph "Frontend (Presentation Layer)"
        P1["Pages"]
        P2["Reusable Components"]
        DM1["Business Module"]
        DM2["Friends Module"]
        DM3["Newsletter Module"]
        DM4["Materials Module"]
        DM5["Suppliers Module"]
        DM6["Posts Module"]
        DM7["Search Module"]
        DM8["Partners Module"]
        GB["Gatsby Build Process"]
    end

    %% Business/State Logic Layer
    subgraph "Business/State Logic"
        GS["Global State"]
        BS["Business State"]
        FS["Friends State"]
        MS["Materials State"]
        SS["Suppliers State"]
        NS["Newsletter State"]
        PS["Posts State"]
        SES["Search State"]
    end

    %% Data/Content Integration Layer
    subgraph "Data/Content Integration"
        LC["Local Content"]
        GQL["GraphQL Data Layer"]
        subgraph "API Services"
            API_N["Newsletter Services"]
            API_Se["Search Services"]
            API_P["Posts Services"]
            API_M["Materials Services"]
            API_S["Suppliers Services"]
        end
    end

    %% Deployment/CI-CD Infrastructure
    subgraph "Deployment/CI/CD"
        DC["Docker & Compose Infrastructure"]
        GHA["GitHub Actions Pipeline"]
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        MOCKS["Mocks & Test Setup"]
        JEST["Jest & Testing Config"]
    end

    %% Connections between layers
    U -->|"interacts"| P1
    P1 -->|"renders"| GS
    P2 --> GS
    DM1 --> GS
    DM2 --> GS
    DM3 --> GS
    DM4 --> GS
    DM5 --> GS
    DM6 --> GS
    DM7 --> GS
    DM8 --> GS

    GB -->|"builds using"| GQL
    LC -->|"provides data to"| GQL
    GQL -->|"supplies content to"| P1

    %% State management interacts with API services
    GS -->|"triggers calls"| API_N
    GS -->|"triggers calls"| API_Se
    GS -->|"triggers calls"| API_P
    GS -->|"triggers calls"| API_M
    GS -->|"triggers calls"| API_S

    %% Deployment and Testing pipelines (external flows)
    GB ---|"build trigger"| DC
    DC ---|"deploys to"| GHA
    MOCKS --- JEST

    %% Classes for coloring
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef state fill:#ABEBC6,stroke:#145A32,stroke-width:2px;
    classDef content fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef deploy fill:#D7BDE2,stroke:#633974,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#943126,stroke-width:2px;

    class U,P1,P2,DM1,DM2,DM3,DM4,DM5,DM6,DM7,DM8,GB frontend;
    class GS,BS,FS,MS,SS,NS,PS,SES state;
    class LC,GQL,API_N,API_Se,API_P,API_M,API_S content;
    class DC,GHA deploy;
    class MOCKS,JEST test;

    %% Click Events - Frontend (Presentation Layer)
    click P1 "https://github.com/klubjagiellonski/pola-web/tree/master/src/pages"
    click P2 "https://github.com/klubjagiellonski/pola-web/tree/master/src/components"
    click DM1 "https://github.com/klubjagiellonski/pola-web/tree/master/src/business"
    click DM2 "https://github.com/klubjagiellonski/pola-web/tree/master/src/friends"
    click DM3 "https://github.com/klubjagiellonski/pola-web/tree/master/src/newsletter"
    click DM4 "https://github.com/klubjagiellonski/pola-web/tree/master/src/materials"
    click DM5 "https://github.com/klubjagiellonski/pola-web/tree/master/src/modules/suppliers"
    click DM6 "https://github.com/klubjagiellonski/pola-web/tree/master/src/posts"
    click DM7 "https://github.com/klubjagiellonski/pola-web/tree/master/src/search"
    click DM8 "https://github.com/klubjagiellonski/pola-web/tree/master/src/partners"
    click GB "https://github.com/klubjagiellonski/pola-web/blob/master/gatsby-config.js"

    %% Click Events - Data/Content Integration
    click LC "https://github.com/klubjagiellonski/pola-web/tree/master/content"
    click GQL "https://github.com/klubjagiellonski/pola-web/blob/master/gatsby-node.js"

    %% Click Events - State Management and Business Logic
    click GS "https://github.com/klubjagiellonski/pola-web/tree/master/src/app/state"
    click BS "https://github.com/klubjagiellonski/pola-web/tree/master/src/business/state"
    click FS "https://github.com/klubjagiellonski/pola-web/tree/master/src/friends/state"
    click MS "https://github.com/klubjagiellonski/pola-web/tree/master/src/materials/state"
    click SS "https://github.com/klubjagiellonski/pola-web/tree/master/src/modules/suppliers/state"
    click NS "https://github.com/klubjagiellonski/pola-web/tree/master/src/newsletter/state"
    click PS "https://github.com/klubjagiellonski/pola-web/tree/master/src/posts/state"
    click SES "https://github.com/klubjagiellonski/pola-web/tree/master/src/search/state"

    %% Click Events - Integration with Backend Services (API Services)
    click API_N "https://github.com/klubjagiellonski/pola-web/tree/master/src/newsletter/services"
    click API_Se "https://github.com/klubjagiellonski/pola-web/tree/master/src/search/services"
    click API_P "https://github.com/klubjagiellonski/pola-web/tree/master/src/posts/services"
    click API_M "https://github.com/klubjagiellonski/pola-web/tree/master/src/materials/services"
    click API_S "https://github.com/klubjagiellonski/pola-web/tree/master/src/modules/suppliers/services"

    %% Click Events - Deployment / CI/CD Infrastructure
    click DC "https://github.com/klubjagiellonski/pola-web/tree/master/Dockerfile"
    click GHA "https://github.com/klubjagiellonski/pola-web/blob/master/.github/workflows/ci.yaml"

    %% Click Events - Testing Infrastructure
    click MOCKS "https://github.com/klubjagiellonski/pola-web/tree/master/__mocks__"
    click JEST "https://github.com/klubjagiellonski/pola-web/blob/master/jest.config.js"
```
