# buildingsmart/validate architecture

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

- Interactive diagram: https://gitdiagram.com/buildingsmart/validate
- Repository: https://github.com/buildingsmart/validate

## Overview

##### Project type and purpose
- This is a full-stack, containerized validation service for IFC files.
- It provides a React-based frontend UI, a Django REST API + Admin backend, an asynchronous Celery worker, a PostgreSQL database, a Redis broker, plus monitoring (Prometheus, OpenTelemetry, Grafana).
- It uses two Git submodules—“ifc-gherkin-rules” and “ifc-validation-data-model”—for validation rules and shared data models.

##### Main components
- Frontend
– React app served over Nginx (supports Let’s Encrypt).
– E2E test harness (Playwright) for UI/API.
- Backend (Django)
– Django Admin UI, REST API (Swagger/Redoc), URL routing, serializers, views.
– Management commands, email templates, authentication.
- Asynchronous Worker
– Celery tasks for syntax, schema, Gherkin, bSDD, signature checks.
– Task runner, processing modules, logger, email notifications.
- Data Store & Broker
– PostgreSQL (persistent storage of requests, results, user data).
– Redis (Celery broker + cache).
- External rule modules (Git submodules)
– IFC Gherkin rules (pytest-driven rule engine).
– Shared Django data model.
- Infrastructure & Monitoring
– Docker Compose orchestrates services.
– Prometheus + OpenTelemetry Collector + Grafana dashboards for metrics.
– Dockerfiles for frontend/backend, Nginx, Grafana provisioning, OTEL, Prometheus.

##### Relationships & data flows
- User → Frontend (browser) → Nginx → React UI
- React UI → HTTP(S) → Django REST API
- API → enqueue validation request → Redis
- Celery Worker → dequeue → execute checks using submodules → write results to PostgreSQL → trigger email tasks
- Django API → poll/read results from PostgreSQL → serve to UI
- Monitoring agents (OTEL) in each container → send metrics to OTEL Collector → Prometheus → Grafana

##### Architectural patterns & principles
- Separation of concerns: UI vs API vs background processing
- Microservice-style isolation in containers
- Event-driven architecture via message broker (Celery + Redis)
- Reusable submodules for rules and shared data model
- Infrastructure as code: Docker Compose, Makefiles, GitHub Actions pipelines

##### Key technologies & frameworks
- Frontend: React, Playwright for E2E, Nginx
- Backend: Python, Django, Django REST Framework, Celery, pytest, pytest-Django
- Data stores: PostgreSQL, Redis
- Monitoring: OpenTelemetry, Prometheus, Grafana
- CI/CD: GitHub Actions, Make, Docker Compose

##### Essential elements
- Clear, consistent labels on each container/service.
- Optional: side-panel listing GitHub Actions workflows and submodule relationships.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface" 
        direction TB
        Browser["User Browser"]:::user
        Frontend["Nginx + React UI"]:::user
    end

    %% Application Services Layer
    subgraph "Application Services"
        direction TB
        DjangoAPI["Django REST API & Admin"]:::app
        CeleryWorker["Celery Worker"]:::app
    end

    %% Data Stores Layer
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL (5432)"]:::infra
        Redis["Redis Broker/Cache (6379)"]:::infra
    end

    %% External Modules Layer
    subgraph "External Rule Modules"
        direction TB
        IFCGherkin["ifc-gherkin-rules"]:::external
        IFCDataModel["ifc-validation-data-model"]:::external
    end

    %% Monitoring Layer
    subgraph "Monitoring & Observability"
        direction TB
        OTELCollector["OTEL Collector"]:::monitor
        Prometheus["Prometheus"]:::monitor
        Grafana["Grafana"]:::monitor
    end

    %% Connections
    Browser -->|"HTTPS 80/443"| Frontend
    Frontend -->|"HTTP(S) 80/443"| DjangoAPI
    DjangoAPI -->|"Enqueue task (Redis 6379)"| Redis
    Redis -->|"Dequeue & run task"| CeleryWorker
    CeleryWorker -->|"Read rules from submodules"| IFCGherkin
    CeleryWorker -->|"Read models from submodules"| IFCDataModel
    CeleryWorker -->|"Write results"| Postgres
    CeleryWorker -->|"Send email tasks"| DjangoAPI
    DjangoAPI -->|"Read results"| Postgres
    DjangoAPI -->|"Serve API to UI"| Frontend

    %% Monitoring Data Flows
    Browser -->|"Metrics"| OTELCollector
    Frontend -->|"Metrics"| OTELCollector
    DjangoAPI -->|"Metrics"| OTELCollector
    CeleryWorker -->|"Metrics"| OTELCollector
    OTELCollector -->|"Scrape"| Prometheus
    Prometheus -->|"Visualize"| Grafana

    %% Click Events
    click Frontend "https://github.com/buildingsmart/validate/tree/main/frontend/src"
    click Frontend "https://github.com/buildingsmart/validate/tree/main/docker/frontend/Dockerfile"
    click Frontend "https://github.com/buildingsmart/validate/blob/main/docker/frontend/.dockerignore"
    click Frontend "https://github.com/buildingsmart/validate/blob/main/docker/frontend/docker-entrypoint.d/99-configure-letsencrypt.sh"
    click Frontend "https://github.com/buildingsmart/validate/blob/main/docker/frontend/nginx/default.conf.template"
    click Browser "https://github.com/buildingsmart/validate/tree/main/e2e/tests"
    click Browser "https://github.com/buildingsmart/validate/blob/main/e2e/playwright.config.js"
    click Browser "https://github.com/buildingsmart/validate/tree/main/e2e/fixtures"
    click Browser "https://github.com/buildingsmart/validate/blob/main/e2e/package.json"
    click Browser "https://github.com/buildingsmart/validate/blob/main/e2e/package-lock.json"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/manage.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/core/settings.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/core/urls.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/core/celery.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/core/email_tasks.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/core/views_auth.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/admin.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/serializers.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/views.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/urls.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/chart_views.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation_bff/views_legacy.py"
    click DjangoAPI "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation_bff/urls.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/task_runner.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/syntax.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/schema.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/gherkin.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/bsdd.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/digital_signatures.py"
    click CeleryWorker "https://github.com/buildingsmart/validate/blob/main/backend/apps/ifc_validation/tasks/processing/instance_completion.py"
    click Postgres "https://github.com/buildingsmart/validate/blob/main/docker-compose.yml"
    click Postgres "https://github.com/buildingsmart/validate/blob/main/docker-compose.full.yml"
    click Postgres "https://github.com/buildingsmart/validate/blob/main/docker-compose.infra_only.yml"
    click Redis "https://github.com/buildingsmart/validate/blob/main/docker-compose.yml"
    click Redis "https://github.com/buildingsmart/validate/blob/main/docker-compose.full.yml"
    click Redis "https://github.com/buildingsmart/validate/blob/main/docker-compose.infra_only.yml"
    click IFCGherkin "https://github.com/buildingsmart/validate/blob/main/.gitmodules"
    click IFCDataModel "https://github.com/buildingsmart/validate/blob/main/.gitmodules"
    click OTELCollector "https://github.com/buildingsmart/validate/blob/main/docker/otel/otel-collector-config.yaml"
    click Prometheus "https://github.com/buildingsmart/validate/blob/main/docker/prometheus/prometheus.yaml"
    click Grafana "https://github.com/buildingsmart/validate/blob/main/docker/grafana/grafana.ini"
    click Grafana "https://github.com/buildingsmart/validate/blob/main/docker/grafana/provisioning/dashboards/opentelemetry-collector.json"
    click Grafana "https://github.com/buildingsmart/validate/blob/main/docker/grafana/provisioning/datasources/default.yaml"

    %% Styles
    classDef user fill:#a2d5c6,stroke:#333,stroke-width:1px;
    classDef app fill:#88b0d9,stroke:#333,stroke-width:1px;
    classDef infra fill:#f5b971,stroke:#333,stroke-width:1px;
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef monitor fill:#c89ec4,stroke:#333,stroke-width:1px;
```
