# cybersecurityluxembourg/openxeco-core architecture

> Architecture diagram of the GitHub repository cybersecurityluxembourg/openxeco-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cybersecurityluxembourg/openxeco-core
- Repository: https://github.com/cybersecurityluxembourg/openxeco-core

## Overview

##### Project type and purpose
- This is a full-stack, multi-component web application (“openXeco core”) comprising:
- A RESTful backend API (oxe-api) implemented in Python/Flask.
- Two single-page React frontends: oxe-web-admin (administrator UI) and oxe-web-community (public/community UI).
- Development and production deployment via Docker (docker-compose).
- Purpose: Manage cybersecurity community data (articles, entities, campaigns, forms, media, users, etc.) through admin and public interfaces, persisting data in MariaDB and sending emails via SMTP.

##### File-structure analysis
- Top-level:
- .docker folder & docker-compose.yml – defines shared Docker network, volumes for MariaDB & media.
- oxe-api/ – Flask app, configuration, resources (API endpoints), migrations (Alembic), Dockerfiles, tests.
- oxe-web-admin/ and oxe-web-community/ – React projects (source under src/, public assets under public/), Dockerfiles, package.json.
- doc/ and README.md – overall documentation & server install instructions.
- Patterns:
- API subfolders organized by resource type (account, article, campaign, …), each exposing CRUD operations.
- Flask uses decorators (authentication, logging, exception handling).
- Migrations via Alembic manage schema evolution.
- Frontends use React components (pages, dialogs, items, forms, charts) connecting to API via HTTP requests (utils/request.jsx).
- Deployment files: Dockerfiles for each service, GitHub Actions workflows for CI/CD.

##### Key README insights
- Single docker-compose up brings up: MariaDB, fake SMTP, API, admin UI, community UI.
- Env vars for DB connection, JWT_SECRET, mail server, storage paths.
- Exposed ports:
- API: 5000 (Flask)
- Admin UI: 3000 (serving React build)
- Community UI: 3001
- SMTP UI: 1080
- MariaDB: 3306

##### Main components
a. Presentation layer
- oxe-web-admin container (React)
- oxe-web-community container (React)
b. API layer
- oxe-api container (Flask application + WSGI)
c. Data layer
- MariaDB container (persistent volume)
- File storage volumes for images and documents (host or Docker volumes)
d. External services
- SMTP server container (fake SMTP for dev/test)
- GitHub Actions CI/CD pipelines (optional)

##### Component interactions and relationships
- User browsers ⇄ HTTP(S) ⇄ React frontends
- React frontends ⇄ REST calls ⇄ Flask API
- Flask API ⇄ SQL queries ⇄ MariaDB
- Flask API ⇄ file I/O ⇄ image/document volumes
- Flask API ⇄ SMTP ⇄ mail delivery
- Docker network “openxeco” connects API, DB, SMTP; frontends connect to API via network aliases or exposed ports.

##### Architectural patterns & principles
- Layered architecture: clear separation between UI, business logic (services/resources), and persistence.
- Modular REST resources: each resource folder in oxe-api implements one business domain.
- Configuration via environment variables (12-factor).
- Containerization: each major component runs in its own Docker container.
- CI/CD: automated builds and security checks via GitHub workflows.
- Database migrations ensure schema versioning (Alembic).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Browser
    User["User Browser"]:::external

    subgraph "Docker Network: openxeco"
        subgraph "Presentation Layer"
            AdminUI["Admin UI (React) :3000"]:::frontend
            CommUI["Community UI (React) :3001"]:::frontend
        end

        subgraph "API Layer"
            API["oxe-api (Flask) :5000"]:::backend
            subgraph "oxe-api Components"
                APIMain["app.py"]:::backend
                APIResource["resource/"]:::backend
                APIRoutes["routes.py"]:::backend
                APIUtils["utils/"]:::backend
                APIConfig["config/"]:::backend
                Migrations["migrations/"]:::storage
                APIDocker[".docker (Dockerfile, entrypoint.sh)"]:::orchestration
            end
        end

        subgraph "Data Layer"
            DB["MariaDB :3306"]:::storage
            Media["Media Volume"]:::storage
        end

        SMTP["SMTP Server :1080"]:::external
    end

    Orchestration["Docker Compose"]:::orchestration

    %% Connections
    User -->|HTTP/HTTPS| AdminUI
    User -->|HTTP/HTTPS| CommUI
    AdminUI -->|REST/HTTP| API
    CommUI -->|REST/HTTP| API
    API -->|SQL| DB
    API -->|File I/O| Media
    API -->|SMTP| SMTP
    Orchestration --> AdminUI
    Orchestration --> CommUI
    Orchestration --> API
    Orchestration --> DB
    Orchestration --> SMTP

    %% Click Events
    click AdminUI "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-web-admin/"
    click CommUI "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-web-community/"
    click API "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/oxe-api/app.py"
    click APIMain "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/oxe-api/app.py"
    click APIResource "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-api/resource/"
    click APIRoutes "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/oxe-api/routes.py"
    click APIUtils "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-api/utils/"
    click APIConfig "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-api/config/"
    click Migrations "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-api/migrations/"
    click APIDocker "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/oxe-api/.docker/Dockerfile"
    click Orchestration "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/docker-compose.yml"
    click DB "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/.docker/mariadb/data/"
    click Media "https://github.com/cybersecurityluxembourg/openxeco-core/tree/main/.docker/media/"

    %% CI/CD
    CI_API["GitHub Actions: API"]:::external
    CI_Admin["GitHub Actions: Admin UI"]:::external
    CI_Comm["GitHub Actions: Community UI"]:::external

    CI_API --> Orchestration
    CI_Admin --> Orchestration
    CI_Comm --> Orchestration

    click CI_API "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/.github/workflows/oxe-api_*.yml"
    click CI_Admin "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/.github/workflows/oxe-web-admin_package.yml"
    click CI_Comm "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/.github/workflows/oxe-web-community_package.yml"

    %% Documentation
    DocAPI["API Configuration Doc"]:::external
    DocInstall["Server Install Doc"]:::external

    DocAPI --> Orchestration
    DocInstall --> Orchestration

    click DocAPI "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/doc/API_CONFIGURATION.md"
    click DocInstall "https://github.com/cybersecurityluxembourg/openxeco-core/blob/main/doc/INSTALL_SERVER.md"

    %% Styling
    classDef frontend fill:#cce5ff,stroke:#0056b3,color:#0056b3;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef storage fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef orchestration fill:#f0f0f0,stroke:#333333,color:#333333;
```
