# flickit-platform/flickit-frontend architecture

> Architecture diagram of the GitHub repository flickit-platform/flickit-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flickit-platform/flickit-frontend
- Repository: https://github.com/flickit-platform/flickit-frontend

## Overview

##### Project Type and Purpose
- Flickit Platform is a Single-Page Application (SPA) built with React, TypeScript, and Vite.
- It provides assessment kits, reporting, comparison, and collaboration features for software teams.
- It runs in Docker, serves static assets via Nginx, and interacts with backend services (not in this repo) over HTTP/REST.

##### File Structure
- Top-level artifacts:
– Dockerfile & nginx/default.conf → containerized deployment.
– vite.config.ts, index.html → SPA build pipeline.
– src/: React code organized by feature (components/, screens/, routes/, providers/, service/, utils/, hooks/).
– cypress/: end-to-end tests.
– .github/workflows/frontend-ci-cd.yaml → CI/CD pipeline for lint, test, build, deploy.
- Architectural patterns:
– Provider pattern (Context + Reducer) for global state (Auth, Assessment, Compare, etc.).
– Service layer abstracts HTTP calls.
– Hooks for shared logic.
– Feature-based component organization (assessment-kit, dashboard, compare, kit-designer…).

##### Additional Insights from README
- Expects a docker-compose setup that includes backend services (APIs, database, Keycloak).
- Nginx serves the built SPA and proxies API requests.
- Authentication likely via Keycloak (see keycloakService.ts).

##### Main Components & Their Interactions
a. Frontend (React SPA)
– Features: Screens, Routes, Components, Hooks, Utils.
– State Management: AppProvider, AuthProvider, AssessmentProvider, etc.
– Service Layer: service/http.tsx + domain-specific modules (assessments, kits, questions…).
– Routing: PrivateRoutes, Redirect.
– Testing: Cypress for E2E, Jest for unit tests in src/components and src/utils.
b. External Services & APIs
– Auth API: Keycloak (token acquisition/refresh).
– Assessment API (REST endpoints).
– ExpertGroup, Questions, Space, User, KitVersions, Advice, Compare services.
c. Deployment
– Docker container runs Nginx, serves built SPA.
– .env.production configures API base URLs.
– GitHub Actions CI/CD: runs ESLint, unit tests, Cypress, builds Docker image, pushes to registry.
d. External Integrations
– Browser → React app → HTTP client → API Gateway
– SPA ←→ Keycloak for auth tokens
– API Gateway → Microservices → Database (not in this repo)

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– Presentation (components/screens) vs business logic (hooks, providers) vs data access (service/).
- Context + Reducer for state slices, promoting unidirectional data flow.
- Feature-based module organization makes it easy to locate code.
- Service abstraction centralizes HTTP configuration (timeouts, base URL, interceptors).
- CI/CD as code via GitHub workflows ensures build/test/deploy consistency.

##### Putting It All Together
- Top-level layer: User’s browser.
- In-App modules:
– Routes/Screens → Components → Providers → Service Layer → HTTP Client
– Hooks and Utils support various features.
- External calls:
– /api/auth → Keycloak
– /api/assessments, /api/assessmentKits, /api/questions, /api/expertGroups, etc.
- Infrastructure: Docker, .env, GitHub Actions, Cypress tests.

- Critical configuration (e.g., API base URLs in .env.production, nginx proxy rules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser
    User["User"]:::user
    Browser["Browser"]:::user

    %% Deployment Layer
    subgraph "Deployment" 
        Dockerfile["Dockerfile"]:::infra
        NginxConf["nginx/default.conf"]:::infra
        DockerContainer["Docker & Nginx"]:::infra
    end

    %% Build Pipeline
    subgraph "Build Pipeline"
        Vite["vite.config.ts"]:::build
        HTML["index.html"]:::build
        TSConfig["tsconfig.json"]:::build
    end

    %% Environment
    subgraph "Environment Config"
        EnvProd[".env.production"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD"
        GHAction[".github/workflows/frontend-ci-cd.yaml"]:::infra
    end

    %% SPA Entry
    subgraph "React SPA"
        Entry["src/main.tsx"]:::app
        AppRoot["src/App.tsx"]:::app
    end

    %% Routing Layer
    subgraph "Routing Layer"
        RIndex["src/routes/index.tsx"]:::app
        RPriv["src/routes/PrivateRoutes.tsx"]:::app
        RRedirect["src/routes/Redirect.tsx"]:::app
    end

    %% Providers
    subgraph "Providers (Context + Reducer)"
        AppProv["src/providers/AppProvider/"]:::app
        AuthProv["src/providers/AuthProvider/"]:::app
        AssessmentProv["src/providers/AssessmentProvider/"]:::app
        CompareProv["src/providers/CompareProvider/"]:::app
        ConfgProv["src/providers/ConfgProvider/"]:::app
        KitProv["src/providers/KitProvider/"]:::app
        QuestionProv["src/providers/QuestionProvider/"]:::app
        ServiceProv["src/providers/ServiceProvider/"]:::app
    end

    %% Service Layer
    subgraph "Service Layer"
        HTTP["src/service/http.tsx"]:::app
        KeycloakSvc["src/service/keycloakService.ts"]:::app
        CommonSvc["src/service/commonService.ts"]:::app
        AdviceSvc["src/service/adviceService.tsx"]:::app
        KitSvcDir["src/service/assessmentKits/"]:::app
        AssessSvcDir["src/service/assessments/"]:::app
        ExpertSvcDir["src/service/expertGroups/"]:::app
        KitVerSvcDir["src/service/kitVersions/"]:::app
        QuestionSvcDir["src/service/questions/"]:::app
        SpaceSvc["src/service/spaceService.tsx"]:::app
        UserSvc["src/service/userService.tsx"]:::app
        ServiceIndex["src/service/index.ts"]:::app
    end

    %% Features: Components & Screens
    subgraph "Feature Code"
        Components["src/components/"]:::app
        Screens["src/screens/"]:::app
    end

    %% Hooks & Utils
    subgraph "Shared Logic"
        Hooks["src/hooks/"]:::app
        Utils["src/utils/"]:::app
    end

    %% Testing
    subgraph "Testing"
        CypressE2E["cypress/e2e/"]:::test
        Commands["cypress/support/commands.ts"]:::test
        CypressConfig["cypress.config.ts"]:::test
    end

    %% External Services
    subgraph "External Services / APIs"
        KeycloakAPI["Keycloak Auth API"]:::external
        AssessAPI["Assessment API"]:::external
        OtherDomain["Other Domain APIs"]:::external
    end

    %% Backend
    subgraph "Backend Microservices"
        Microservices["Microservices"]:::external
        Database["Database"]:::external
    end

    %% Connections
    User --> Browser
    Browser --> DockerContainer
    Dockerfile --> DockerContainer
    NginxConf --> DockerContainer

    DockerContainer --> Vite
    DockerContainer --> HTML
    DockerContainer --> TSConfig
    EnvProd --> DockerContainer

    GHAction --> DockerContainer
    GHAction --> Vite
    GHAction --> HTML

    DockerContainer --> Entry
    Entry --> AppRoot

    AppRoot --> RIndex
    AppRoot --> AppProv
    AppRoot --> HTTP
    AppRoot --> Components
    AppRoot --> Screens
    AppRoot --> Hooks
    AppRoot --> Utils

    RIndex --> RPriv
    RIndex --> RRedirect

    AppProv --> AssessmentProv
    AppProv --> AuthProv
    AppProv --> CompareProv
    AppProv --> ConfgProv
    AppProv --> KitProv
    AppProv --> QuestionProv
    AppProv --> ServiceProv

    HTTP --> KeycloakAPI
    HTTP --> AssessAPI
    HTTP --> OtherDomain

    KeycloakAPI --> Microservices
    AssessAPI --> Microservices
    OtherDomain --> Microservices
    Microservices --> Database

    %% Click Events
    click Dockerfile "https://github.com/flickit-platform/flickit-frontend/tree/main/Dockerfile"
    click NginxConf "https://github.com/flickit-platform/flickit-frontend/blob/main/nginx/default.conf"
    click Vite "https://github.com/flickit-platform/flickit-frontend/blob/main/vite.config.ts"
    click HTML "https://github.com/flickit-platform/flickit-frontend/blob/main/index.html"
    click TSConfig "https://github.com/flickit-platform/flickit-frontend/blob/main/tsconfig.json"
    click EnvProd "https://github.com/flickit-platform/flickit-frontend/blob/main/.env.production"
    click GHAction "https://github.com/flickit-platform/flickit-frontend/blob/main/.github/workflows/frontend-ci-cd.yaml"
    click Entry "https://github.com/flickit-platform/flickit-frontend/blob/main/src/main.tsx"
    click AppRoot "https://github.com/flickit-platform/flickit-frontend/blob/main/src/App.tsx"
    click RIndex "https://github.com/flickit-platform/flickit-frontend/blob/main/src/routes/index.tsx"
    click RPriv "https://github.com/flickit-platform/flickit-frontend/blob/main/src/routes/PrivateRoutes.tsx"
    click RRedirect "https://github.com/flickit-platform/flickit-frontend/blob/main/src/routes/Redirect.tsx"
    click AppProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/AppProvider/"
    click AuthProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/AuthProvider/"
    click AssessmentProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/AssessmentProvider/"
    click CompareProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/CompareProvider/"
    click ConfgProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/ConfgProvider/"
    click KitProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/KitProvider/"
    click QuestionProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/QuestionProvider/"
    click ServiceProv "https://github.com/flickit-platform/flickit-frontend/tree/main/src/providers/ServiceProvider/"
    click HTTP "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/http.tsx"
    click KeycloakSvc "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/keycloakService.ts"
    click CommonSvc "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/commonService.ts"
    click AdviceSvc "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/adviceService.tsx"
    click KitSvcDir "https://github.com/flickit-platform/flickit-frontend/tree/main/src/service/assessmentKits/"
    click AssessSvcDir "https://github.com/flickit-platform/flickit-frontend/tree/main/src/service/assessments/"
    click ExpertSvcDir "https://github.com/flickit-platform/flickit-frontend/tree/main/src/service/expertGroups/"
    click KitVerSvcDir "https://github.com/flickit-platform/flickit-frontend/tree/main/src/service/kitVersions/"
    click QuestionSvcDir "https://github.com/flickit-platform/flickit-frontend/tree/main/src/service/questions/"
    click SpaceSvc "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/spaceService.tsx"
    click UserSvc "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/userService.tsx"
    click ServiceIndex "https://github.com/flickit-platform/flickit-frontend/blob/main/src/service/index.ts"
    click Components "https://github.com/flickit-platform/flickit-frontend/tree/main/src/components/"
    click Screens "https://github.com/flickit-platform/flickit-frontend/tree/main/src/screens/"
    click Hooks "https://github.com/flickit-platform/flickit-frontend/tree/main/src/hooks/"
    click Utils "https://github.com/flickit-platform/flickit-frontend/tree/main/src/utils/"
    click CypressE2E "https://github.com/flickit-platform/flickit-frontend/tree/main/cypress/e2e/"
    click Commands "https://github.com/flickit-platform/flickit-frontend/blob/main/cypress/support/commands.ts"
    click CypressConfig "https://github.com/flickit-platform/flickit-frontend/blob/main/cypress.config.ts"

    %% Styles
    classDef user fill:#9f6,stroke:#333,stroke-width:1px
    classDef infra fill:#f96,stroke:#333,stroke-width:1px
    classDef build fill:#6cf,stroke:#333,stroke-width:1px
    classDef app fill:#6fa,stroke:#333,stroke-width:1px
    classDef external fill:#fc6,stroke:#333,stroke-width:1px
    classDef test fill:#c6f,stroke:#333,stroke-width:1px
```
