# colloqi/pisignage-server architecture

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

- Interactive diagram: https://gitdiagram.com/colloqi/pisignage-server
- Repository: https://github.com/colloqi/pisignage-server

## Overview

##### Project Purpose and Type
- This is a full-stack server application designed to manage and update piSignage players on a LAN or private network. The server handles player management, group and asset administration, playlist management, and even media conversion. It also includes both server-side processing (Node.js backend) and client-side functionality (AngularJS-based front-end).

##### Main Components
a. Backend Server (Node.js Application):
- The “server.js” file is the entry point.
- The “app” directory implements the MVC (or similar) pattern:
- Controllers (in app/controllers) handle the business logic for assets, players, groups, Google Calendar integration (gcal.js), licensing, and more.
- Models (in app/models) represent data entities such as players, assets, groups, labels, settings.
- Helpers and utilities in app/others.
- Views for error pages and layout templates (in app/views) used to render server responses.
- Configuration files (in config and its env subdirectories) define environment-specific settings, routes, and express middleware.

b. Frontend Client (AngularJS Application):
- The “public” folder contains the web application:
- Angular controllers, services, directives, filters (located in public/app/js).
- Static assets such as CSS, fonts, images, partials (HTML/Pug templates) that render the UI.
- This layer interacts with the backend via REST endpoints.

c. Data Management and External Services:
- MongoDB is used as the database, as indicated by README instructions and configuration details.
- External media processing tools (ffmpeg, ffprobe, and ImageMagick) are integrally mentioned for video conversion and thumbnail generation.

d. Infrastructure and Deployment:
- Docker integration is evident with a Dockerfile, .dockerignore, and docker-compose (both for development and production).
- There are additional scripts for installing dependencies on various OS platforms (in the “scripts” folder).
- GitHub CI/CD (GitHub workflows and Docker build instructions) are in the .github folder.

##### Relationships and Data Flow
- The backend controllers handle requests (e.g., for assets upload, player management, group assignments) and interact with models to update MongoDB.
- The asset workflow involves media uploads, after which the server triggers external processing (ffmpeg for video conversion and ImageMagick for thumbnails). Indicate data flows from incoming media to external processing services and back to persistent storage.
- Players connect to the server for configuration and software updates; include communication between the piSignage players (client devices) and the server.
- Docker components encapsulate the server (and possibly MongoDB) in containers, which should be represented as a containerization layer.

##### Architectural Patterns and Design Principles
- Separation of concerns (frontend vs. backend, and clear MVC separation within the server code).
- Use of RESTful interfaces for communication between the frontend and backend.
- Modular design: individual controllers and models for different functions (assets, player management, playlists, etc.) and the extensible Docker/CI configuration for deployment.
- The design also supports scalability via Docker volumes for media and data directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Frontend Client (AngularJS)"]:::frontend
        FE_Static["Static Assets (public)"]:::frontend
        FE_JS["AngularJS Code (public/app/js)"]:::frontend
        FE_Partials["Templates & Partials (public/app/partials)"]:::frontend
        FE_Templates["Additional Templates (public/app/templates)"]:::frontend
    end

    %% Application/Business Logic Layer
    subgraph "Application Layer"
        BE["Backend Server (Node.js)"]:::backend
        BE_Server["Entry Point: server.js"]:::backend
        MVC["MVC Components (app)"]:::backend
        BE_Config["Configuration (config)"]:::backend
        
        subgraph "MVC Components"
            Controllers["Controllers (app/controllers)"]:::backend
            Models["Models (app/models)"]:::backend
            Helpers["Helpers/Utilities (app/others)"]:::backend
            Views["Views (app/views)"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["MongoDB Database"]:::data
        DataStore["Media & Releases (data)"]:::data
    end

    %% External Services
    subgraph "External Services"
        FFMPEG["ffmpeg"]:::external
        FFPROBE["ffprobe"]:::external
        IMAGEMAGICK["ImageMagick"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        subgraph "Docker Deployment"
            Dockerfile["Dockerfile"]:::infrastructure
            DockerCompose["docker-compose.yml"]:::infrastructure
            DockerComposeProd["docker-compose.prod.yml"]:::infrastructure
            DockerIgnore[".dockerignore"]:::infrastructure
        end
        CICD["CI/CD (.github)"]:::infrastructure
    end

    %% piSignage Players
    Players["piSignage Players Devices"]:::external

    %% Connections
    FE -->|"API_calls"| BE
    FE_Static --> FE
    FE_JS --> FE
    FE_Partials --> FE
    FE_Templates --> FE

    BE -->|"REST_CRUD"| DB
    BE -->|"MediaProcessing"| FFMPEG
    BE -->|"MediaProcessing"| FFPROBE
    BE -->|"MediaProcessing"| IMAGEMAGICK
    BE -->|"Updates"| Players
    BE_Server --> MVC
    BE_Server --> BE_Config
    MVC --> Controllers
    MVC --> Models
    MVC --> Helpers
    MVC --> Views
    MVC -->|"StoresReleases"| DataStore

    Dockerfile --> BE
    DockerCompose --> BE
    DockerComposeProd --> BE
    DockerIgnore --> BE
    CICD --> Dockerfile
    CICD --> DockerCompose
    CICD --> DockerComposeProd
    CICD --> DockerIgnore
    Dockerfile --- DB

    %% Class definitions with colors
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef data fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infrastructure fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events for Backend
    click BE_Server "https://github.com/colloqi/pisignage-server/blob/master/server.js"
    click MVC "https://github.com/colloqi/pisignage-server/tree/master/app"
    click BE_Config "https://github.com/colloqi/pisignage-server/tree/master/config"
    click Controllers "https://github.com/colloqi/pisignage-server/tree/master/app/controllers"
    click Models "https://github.com/colloqi/pisignage-server/tree/master/app/models"
    click Helpers "https://github.com/colloqi/pisignage-server/tree/master/app/others"
    click Views "https://github.com/colloqi/pisignage-server/tree/master/app/views"

    %% Click Events for Frontend
    click FE_Static "https://github.com/colloqi/pisignage-server/tree/master/public"
    click FE_JS "https://github.com/colloqi/pisignage-server/tree/master/public/app/js"
    click FE_Partials "https://github.com/colloqi/pisignage-server/tree/master/public/app/partials"
    click FE_Templates "https://github.com/colloqi/pisignage-server/tree/master/public/app/templates"

    %% Click Event for Data Storage
    click DataStore "https://github.com/colloqi/pisignage-server/tree/master/data"

    %% Click Events for Infrastructure & Deployment
    click Dockerfile "https://github.com/colloqi/pisignage-server/tree/master/Dockerfile"
    click DockerCompose "https://github.com/colloqi/pisignage-server/blob/master/docker-compose.yml"
    click DockerComposeProd "https://github.com/colloqi/pisignage-server/blob/master/docker-compose.prod.yml"
    click DockerIgnore "https://github.com/colloqi/pisignage-server/blob/master/.dockerignore"
    click CICD "https://github.com/colloqi/pisignage-server/blob/master/.github"
```
