# more-platform/more-limesurvey architecture

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

- Interactive diagram: https://gitdiagram.com/more-platform/more-limesurvey
- Repository: https://github.com/more-platform/more-limesurvey

## Overview

##### Project Overview & Purpose
- This project is a specialized repackaging of Limesurvey that is “MORE-specific.” Its primary purpose is to run Limesurvey (a survey management tool) inside Docker for development and testing.
- The README clearly outlines that Docker Compose will launch the Limesurvey container locally while integrating an OAuth2 based SSO mechanism (with Keycloak) via a custom plugin. In addition, the project supports a JSON-RPC API for remote control of surveys.

##### And List Main Components
- Docker Infrastructure:
- Dockerfile: Defines the custom Docker image for Limesurvey, pre-packaged with the OAuth2 (AuthOAuth2) plugin.
- docker-compose.yaml: Manages multi-container configuration (although likely a single container for Limesurvey, this file coordinates the startup).
- Limesurvey Application:
- The core Limesurvey system available on http://localhost:8080 once the container is running.
- Administrative backend at /index.php/admin, through which plugin activation and configuration (like scanning for plugins) is managed.
- OAuth2 Integration:
- External authentication via Keycloak (SSO) for logging into Limesurvey. This involves specific OAuth endpoints (authorize URL, token URL, etc.) that will interact with the internal plugin.
- The plugin (AuthOAuth2) integrated within the Docker image requires scanning and activation from the Limesurvey admin panel.
- JSON-RPC API:
- Enabled API endpoints for survey control such as get_session_key, add_survey, activate_tokens, etc.
- A possible client-side tool (insomnia/limesurvey-api.json) for testing these API endpoints.
- Documentation & Dev Tools:
- The doc directory contains images (screenshots) that illustrate configuration steps (JSON-RPC setup, etc.).
- GitHub workflows and Dependabot configuration under .github indicate CI/CD and dependency management.

##### Relationships and Data Flows
- External User/Client:
- Initiates requests either through a web browser (interacting with the Limesurvey UI) or via API calls (using JSON-RPC).
- Docker Compose Orchestrator:
- Launches the Limesurvey container, which encapsulates the Limesurvey application modified as per the MORE specific repackaging.
- Limesurvey Application & Plugin:
- Processes web requests from the browser and API calls.
- Uses the OAuth2 plugin to redirect or authenticate users via Keycloak for Single Sign-On.
- Keycloak (External Auth Server):
- JSON-RPC API Calls:
- Session creation and specific operations (add survey, activate survey, etc.) that require the client to obtain a session key.

##### Architectural Patterns & Important Principles
- Containerization: The use of a Dockerfile and docker-compose system isolates deployment, which should be depicted by grouping components within a “Docker Container” boundary.
- Modular Integration: Notice how the OAuth2 plugin is an add-on module scanned and configured within Limesurvey’s admin interface. This modular design should be clearly delineated.
- Client-Server Interaction: Demonstrate clearly the separation between the front-end user interface of Limesurvey and back-end API interactions (via JSON-RPC).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        DF["Dockerfile"]:::docker
        DCY["docker-compose.yaml"]:::docker
    end

    %% Limesurvey Container
    subgraph "Limesurvey Container"
        LS_UI["Limesurvey Application (UI)"]:::application
        API["JSON-RPC API"]:::application
        OAUTH["OAuth2 Plugin (AuthOAuth2)"]:::application
    end

    %% Development and Documentation
    subgraph "Dev & Documentation"
        DOC["Project Documentation"]:::devops
        CI["CI/CD (GitHub Workflows & Dependabot)"]:::devops
        INS["JSON-RPC API Testing (Insomnia)"]:::devops
    end

    %% External Services
    CLIENT["Client (Browser/API)"]:::external
    KC["Keycloak Auth Server"]:::external

    %% Relationships for Deployment Infrastructure to Container
    DF -->|"BuildsImage"| LS_UI
    DCY -->|"LaunchesContainer"| LS_UI
    CI -->|"TriggersBuild"| LS_UI
    DOC -.->|"Documents"| LS_UI

    %% User interactions
    CLIENT -->|"UIRequest"| LS_UI
    CLIENT -->|"APICall"| API
    INS -->|"TestsAPI"| API

    %% OAuth2 Integration
    LS_UI -->|"SSORedirect"| OAUTH
    OAUTH -->|"RequestAuth"| KC
    KC -->|"ReturnToken"| OAUTH

    %% Click Events
    click DF "https://github.com/more-platform/more-limesurvey/tree/main//Dockerfile"
    click DCY "https://github.com/more-platform/more-limesurvey/blob/main//docker-compose.yaml"
    click INS "https://github.com/more-platform/more-limesurvey/blob/main//insomnia/limesurvey-api.json"
    click DOC "https://github.com/more-platform/more-limesurvey/tree/main//doc"
    click CI "https://github.com/more-platform/more-limesurvey/tree/main//github"

    %% Styles
    classDef docker fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef application fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
    classDef external fill:#ffebee,stroke:#b71c1c,stroke-width:2px;
    classDef devops fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;
```
