# mff-uk/dataspecer architecture

> Architecture diagram of the GitHub repository mff-uk/dataspecer, 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/mff-uk/dataspecer
- Repository: https://github.com/mff-uk/dataspecer

## Overview

##### Major System Components
- Applications: Represented by the “applications” directory, these are the various web client projects (for example, the API specification app, the conceptual model editor, the data specification editor, and the manager). They interact with users via UIs developed in frameworks like React and Vite.
- Services / Backend: Under “services/backend” you have the core backend service that handles storage (the database/db file and the stores directory) and implements APIs, routes, and business logic (including Prisma migrations and REST endpoints). Incorporate its dependencies to external systems.
- Packages: The “packages” folder contains many utilities and domain-specific libraries (e.g., core-v2, csv, ldkit, opneapi, rdfs-adapter, sgov-adapter, etc.). These packages fulfill various roles: implementing domain logic, performing artifact generation, processing data specifications, and handling adapters for different data formats.
- Infrastructure & DevOps: Components such as Docker (with Dockerfile, docker-compose details), Turborepo, npm workspaces, and Cloudflare Pages (as referenced in the README) are part of the orchestration and deployment process.

##### Important Architectural Patterns
- And annotate any middleware or integration points (e.g., communication with external services like Cloudflare Pages or the use of Docker for containerized deployment).
- Where configuration and environment settings are made available (for instance, the use of environment variables such as BASE_URL, and user configurations for Docker).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Web Applications – Client UIs (React/Vite)"
        A1["API Specification App"]:::app
        A2["Conceptual Model Editor"]:::app
        A3["Data Specification Editor"]:::app
        A4["Manager"]:::app
    end

    subgraph "Backend Service"
        B1["Backend Service – API/Business Logic (NodeJS+Prisma)"]:::backend
        B2["Database/Store"]:::database
    end

    subgraph "Shared Packages – Common Utilities"
        P1["core-v2"]:::package
        P2["csv"]:::package
        P3["ldkit"]:::package
        P4["openapi"]:::package
        P5["rdfs-adapter"]:::package
        P6["sgov-adapter"]:::package
        P7["shacl"]:::package
    end

    subgraph "Infrastructure & DevOps"
        I1["Docker & DevOps Files"]:::infra
        I2[".dockerignore"]:::infra
        I3["turbo.json"]:::infra
        I4[".github/workflows"]:::infra
        I5["package.json (npm workspaces)"]:::infra
        I6["docker/ws"]:::infra
        I7["utils/testing-environment"]:::infra
    end

    %% Data flows from Clients to Backend
    A1 -->|"HTTP_Request"| B1
    A2 -->|"HTTP_Request"| B1
    A3 -->|"HTTP_Request"| B1
    A4 -->|"HTTP_Request"| B1

    %% Backend interacts with its Database/Store
    B1 -->|"Reads/Writes"| B2

    %% Both Backend and Clients depend on Shared Packages
    B1 -->|"Uses"| P1
    B1 -->|"Uses"| P2
    B1 -->|"Uses"| P3
    B1 -->|"Uses"| P4
    B1 -->|"Uses"| P5
    B1 -->|"Uses"| P6
    B1 -->|"Uses"| P7

    A1 -->|"DependsOn"| P1
    A2 -->|"DependsOn"| P1
    A3 -->|"DependsOn"| P1
    A4 -->|"DependsOn"| P1

    %% Infrastructure orchestrates deployments and builds
    I1 ---|"Orchestrates"| A1
    I1 ---|"Orchestrates"| B1
    I1 ---|"Orchestrates"| P1

    %% Infrastructure files interconnection
    I1 --- I2
    I1 --- I3
    I1 --- I4
    I1 --- I5
    I1 --- I6
    I1 --- I7

    %% Click Events for Web Applications
    click A1 "https://github.com/mff-uk/dataspecer/tree/main/applications/api-specification"
    click A2 "https://github.com/mff-uk/dataspecer/tree/main/applications/conceptual-model-editor"
    click A3 "https://github.com/mff-uk/dataspecer/tree/main/applications/data-specification-editor"
    click A4 "https://github.com/mff-uk/dataspecer/tree/main/applications/manager"

    %% Click Event for Backend Service
    click B1 "https://github.com/mff-uk/dataspecer/tree/main/services/backend"

    %% Click Events for Shared Packages
    click P1 "https://github.com/mff-uk/dataspecer/tree/main/packages/core-v2"
    click P2 "https://github.com/mff-uk/dataspecer/tree/main/packages/csv"
    click P3 "https://github.com/mff-uk/dataspecer/tree/main/packages/ldkit"
    click P4 "https://github.com/mff-uk/dataspecer/tree/main/packages/openapi"
    click P5 "https://github.com/mff-uk/dataspecer/tree/main/packages/rdfs-adapter"
    click P6 "https://github.com/mff-uk/dataspecer/tree/main/packages/sgov-adapter"
    click P7 "https://github.com/mff-uk/dataspecer/tree/main/packages/shacl"

    %% Click Events for Infrastructure & DevOps files
    click I1 "https://github.com/mff-uk/dataspecer/tree/main/Dockerfile"
    click I2 "https://github.com/mff-uk/dataspecer/blob/main/.dockerignore"
    click I3 "https://github.com/mff-uk/dataspecer/blob/main/turbo.json"
    click I4 "https://github.com/mff-uk/dataspecer/tree/main/.github/workflows"
    click I5 "https://github.com/mff-uk/dataspecer/blob/main/package.json"
    click I6 "https://github.com/mff-uk/dataspecer/tree/main/docker/ws"
    click I7 "https://github.com/mff-uk/dataspecer/tree/main/utils/testing-environment"

    %% Styles
    classDef app fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef backend fill:#bbdefb,stroke:#1565c0,stroke-width:2px;
    classDef database fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef package fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef infra fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
```
