# nc-apps/quex architecture

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

- Interactive diagram: https://gitdiagram.com/nc-apps/quex
- Repository: https://github.com/nc-apps/quex

## Overview

##### Project Overview
- Project Type & Purpose: This is a full-stack web application built in Rust (using Cargo and Rust’s conventions) that provides UX questionnaires such as AttrakDiff, Net Promoter Score, and System Usability Score. The project also features a modern frontend driven by Tailwind CSS for styling, and it supports authentication through OpenID Connect and token-based mechanisms.
- Key Purposes: Collect UX survey responses, display interactive survey pages, manage user authentication (via cookies and tokens), and support internationalization through translation files.

##### File Structure
- Backend Code (Rust):
- The “src” directory contains the application’s main logic with modules for authentication (src/auth), routes (src/routes, including submodules for surveys and error handling), database operations (src/database with SQL scripts for table creation), and additional business logic (preferred_language, translation).
- There is a main entry point in src/main.rs.
- Frontend Components:
- “templates” holds HTML templates organized by functionality: authentication pages, survey pages (including forms and response/result view pages), and a general layout division that separates common elements (base, authenticated layout).
- “public” contains static assets and client-side files.
- Tailwind configuration (tailwind.config.js and tailwind.css) and package management files (package.json, pnpm-lock.yaml) indicate that Tailwind is used to build styles.
- Infrastructure & Deployment:
- Dockerfile is present for containerization.
- GitHub Actions workflows (.github/workflows) provide CI/CD pipelines for building (both Docker and “quex” itself) and deploying the application.
- Docs provide additional context, like entity relationships and UX questionnaires details.
- Authentication Details:
- Several authentication methods are implemented: OpenID Connect flow (src/auth/open_id_connect) and token-based authentication (src/auth/token), with supplementary modules for signing and cookie management.
- Internationalization:
- “translations” directory with separate folders for “de” and “en” indicates a multilingual approach using .ftl files.

a. Client & Browser Interface:
- Interaction via HTTP(s) to the web server.
b. Web Server (Backend in Rust):
- Main Application Module (src/main.rs) as the central controller.
- Routing Module: “Routes” submodules for index, errors, and various surveys.
- Authentication Module: Separate components for handling OpenID Connect, cookies, and token-based authentication.
- Database Module: Display an external “Database” (e.g., PostgreSQL) that is interfaced via SQL scripts (src/database/create_tables.sql). Indicate that the DB stores survey data, user info, and responses.
- Translation Module: Represents internationalization support, interfacing with the “translations” directory.
c. Frontend/Presentation Layer:
- Templates: The HTML templates that generate the user interface (located in the “templates” directory). Highlight that there are different layouts (base, authenticated) and separate templates for authentication and surveys.
- Static Assets: Represent “public” with CSS/JS and assets.
- Tailwind CSS: Note that Tailwind CSS compiles styles using npm scripts.
d. External Services & CI/CD:
- GitHub Workflows: Show CI/CD tools (builds and deploys).
- Docker: Represent the containerization via Dockerfile.

##### Component Relationships & Interactions
- Data Flow:
- The client sends requests to the web server.
- The server processes routes, checks authentication (via the auth modules), queries/inserts data into the database as needed, and returns appropriate views (HTML generated from templates).
- Authentication interactions may involve external OpenID Connect providers.
- Separation of Concerns:
- The authentication module separates concerns for user identity management.
- The survey routes are isolated from other application logic to clearly manage different survey types (each with their own templates).
- Infrastructure:
- CI/CD pipelines automatically build and deploy the application.
- Docker containerization handles application deployment.

##### Architectural Patterns & Notable Technologies
- MVC-Like Pattern: Although not a strict MVC, the separation of routes (controller), templates (view), and database operations (model) reflects a clean separation.
- Authentication Design: Modular design supporting OpenID Connect, token management, and cookie-based sessions.
- Deployment & DevOps: Use of GitHub Actions workflows and Docker for standardized builds and deployment.
- Tailwind CSS: Frontend styling managed via Tailwind configuration and build processes.
- Internationalization: Translation files per language for dynamic rendering of UI text.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        WB["Web Browser"]:::frontend
    end

    %% Backend (Rust Application)
    subgraph "Backend (Rust Application)"
        mainApp["Main Application Module (src/main.rs)"]:::backend
        routes["Routing Module (src/routes)"]:::backend
        auth["Authentication Module (OIDC & Tokens) (src/auth)"]:::backend
        db["Database Module (PostgreSQL) (src/database)"]:::database
        trans["Translation Module (src/translation.rs & translations)"]:::backend
        exAuth["External OIDC Provider"]:::external
    end

    %% Frontend (Presentation Layer)
    subgraph "Frontend (Presentation Layer)"
        templates["Templates (HTML) (templates)"]:::frontend
        assets["Static Assets (CSS/JS) (public)"]:::frontend
        tailwind["Tailwind CSS & Assets (tailwind.config.js, tailwind.css, package.json, pnpm-lock.yaml)"]:::frontend
    end

    %% Infrastructure (DevOps)
    subgraph "Infrastructure (DevOps)"
        cicd["CI/CD Pipelines (.github/workflows)"]:::infrastructure
        docker["Containerization (Dockerfile)"]:::infrastructure
    end

    %% Connections between layers
    WB -->|"HTTPRequest"| mainApp
    mainApp -->|"dispatch"| routes
    mainApp -->|"authCheck"| auth
    auth -->|"OIDCFlow"| exAuth
    mainApp -->|"DBQuery"| db
    mainApp -->|"i18nLookup"| trans
    mainApp -->|"renderHTML"| templates
    templates -->|"HTTPResponse"| WB
    tailwind -->|"applyStyles"| templates
    assets -->|"embedAssets"| templates

    cicd -->|"buildDeploy"| docker
    docker -->|"deploy"| mainApp

    %% Class definitions for styling
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef database fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef infrastructure fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;

    %% Click Events for Component Mapping
    click mainApp "https://github.com/nc-apps/quex/blob/main/src/main.rs"
    click routes "https://github.com/nc-apps/quex/tree/main/src/routes"
    click auth "https://github.com/nc-apps/quex/tree/main/src/auth"
    click db "https://github.com/nc-apps/quex/tree/main/src/database"
    click trans "https://github.com/nc-apps/quex/blob/main/src/translation.rs"
    click templates "https://github.com/nc-apps/quex/tree/main/templates"
    click assets "https://github.com/nc-apps/quex/tree/main/public"
    click tailwind "https://github.com/nc-apps/quex/blob/main/tailwind.config.js"
    click cicd "https://github.com/nc-apps/quex/tree/main/.github/workflows"
    click docker "https://github.com/nc-apps/quex/tree/main/Dockerfile"
```
