# actidoo/gamification-engine architecture

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

- Interactive diagram: https://gitdiagram.com/actidoo/gamification-engine
- Repository: https://github.com/actidoo/gamification-engine

## Overview

##### Project type and purpose
- This is an open-source, full-stack “service” framework (gamification-engine) written in Python (Pyramid) that exposes a REST API and ships a React/JS admin UI.
- Its purpose is to let any application “talk” to it (over REST) to manage achievements, leaderboards, triggers, time-zone aware evaluations, caching, push notifications, etc.

##### File structure
- Top level:
- Docker & CI configs: Dockerfile, docker-compose.yml(.production), travis.yml
- Python package metadata: setup.py, requirements.txt, MANIFEST.in
- Configs: development.ini, production.ini (in docker-files), uwsgi/nginx configs
- gengine/app: the Pyramid application
- api/ (resources.py, schemas.py) → REST controllers
- alembic/ → DB migrations (SQLAlchemy + Alembic)
- jsscripts/ → React frontend code & built static assets
- tasks.py, tasksystem.py & maintenance/scripts/ → background scheduler & workers
- cache.py → dogpile.cache integration
- push.py → push notification triggers
- model.py → SQLAlchemy models
- templates/static/ → admin UI templates & JS components
- tests/ → unit/integration tests
- gengine/base: shared utilities, settings, context, caching, error handling
- Top-level scripts: init.sh, wait-for-it.sh, paster-script.py

##### README for additional insights
- Confirms: Python service with REST interface, admin UI
- Dependencies: Pyramid, SQLAlchemy, Alembic, dogpile.cache (memcached), Flask-admin, psycopg2 (PostgreSQL), etc.
- Docker support: docker-compose for dev & prod
- Maintenance scripts manage DB init, migrations, scheduler beat & worker, push messages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        ReactApp["React Admin UI"]:::frontend
    end

    %% Backend Services Container
    subgraph "Backend Service Container"
        Nginx["Nginx Reverse Proxy\n(HTTP/HTTPS: 80/443)"]:::backend
        UWSGI["uWSGI / Pyramid\n(REST API Service)"]:::backend
    end

    %% Pyramid Application Components
    subgraph "Pyramid Application"
        API["REST API Controllers"]:::backend
        Business["Business Logic & Formulas"]:::backend
        Models["SQLAlchemy Models"]:::data
        Migrations["Alembic Migrations"]:::data
        CacheLayer["Cache Integration\n(dogpile.cache)"]:::data
        PushTrigger["Push Notification Triggers"]:::backend
    end

    %% Asynchronous Processing
    subgraph "Asynchronous Processing"
        Scheduler["Background Scheduler"]:::async
        Worker["Background Worker"]:::async
        TaskSystem["Task System & Definitions"]:::async
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::data
        Memcached["Memcached"]:::data
    end

    %% External Services
    subgraph "External Services"
        PushServices["Push Notification Services\n(FCM / APNs)"]:::external
    end

    %% DevOps & Deployment
    subgraph "Deployment & CI/CD"
        DockerCompose["Docker Compose"]:::infra
        TravisCI["Travis CI"]:::infra
        Configs["Config & Deployment Files"]:::infra
    end

    %% Connections
    ReactApp -->|HTTP/HTTPS| Nginx
    Nginx -->|Proxy REST API| UWSGI

    UWSGI --> API
    API --> Business
    Business --> Models
    Business --> CacheLayer
    Business --> PushTrigger

    Models --> Postgres
    CacheLayer --> Memcached

    Scheduler -->|enqueue jobs| TaskSystem
    TaskSystem --> Postgres
    Worker --> TaskSystem
    Worker -->|send notifications| PushServices
    PushTrigger -->|push events| PushServices

    %% DevOps Flows
    DockerCompose --> Nginx
    DockerCompose --> Postgres
    DockerCompose --> Memcached
    TravisCI --> DockerCompose
    Configs --> DockerCompose

    %% Click Events
    click API "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/api/resources.py"
    click API "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/api/schemas.py"
    click UWSGI "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/route.py"
    click UWSGI "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/views.py"
    click UWSGI "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/registries.py"
    click Models "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/model.py"
    click Migrations "https://github.com/actidoo/gamification-engine/tree/master/gengine/app/alembic/"
    click CacheLayer "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/cache.py"
    click CacheLayer "https://github.com/actidoo/gamification-engine/blob/master/gengine/base/cache.py"
    click Business "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/formular.py"
    click PushTrigger "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/push.py"
    click TaskSystem "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/tasks.py"
    click TaskSystem "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/tasksystem.py"
    click Scheduler "https://github.com/actidoo/gamification-engine/blob/master/gengine/maintenance/scripts/scheduler_beat.py"
    click Worker "https://github.com/actidoo/gamification-engine/blob/master/gengine/maintenance/scripts/scheduler_worker.py"
    click ReactApp "https://github.com/actidoo/gamification-engine/tree/master/gengine/app/jsscripts/src/"
    click ReactApp "https://github.com/actidoo/gamification-engine/tree/master/gengine/app/jsscripts/build/"
    click ReactApp "https://github.com/actidoo/gamification-engine/blob/master/gengine/app/jsscripts/public/index.html"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/development.ini"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/docker-files/production.ini"
    click DockerCompose "https://github.com/actidoo/gamification-engine/blob/master/docker-compose.yml"
    click DockerCompose "https://github.com/actidoo/gamification-engine/blob/master/docker-compose.production.yml"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/docker-files/*.uwsgi"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/docker-files/nginx-*.conf"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/gengine/wsgiutil.py"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/paster-script.py"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/init.sh"
    click Configs "https://github.com/actidoo/gamification-engine/blob/master/wait-for-it.sh"

    %% Styles
    classDef frontend fill:#ACE,stroke:#333,stroke-width:1px;
    classDef backend fill:#8DF,stroke:#333,stroke-width:1px;
    classDef data fill:#BDF,stroke:#333,stroke-width:1px;
    classDef async fill:#FED,stroke:#333,stroke-width:1px;
    classDef external fill:#FEE,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef infra fill:#DDD,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
