# cetorres/acsp4hr_project architecture

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

- Interactive diagram: https://gitdiagram.com/cetorres/acsp4hr_project
- Repository: https://github.com/cetorres/acsp4hr_project

## Overview

##### Project type and purpose
- This is a full-stack web application (SPDS) for secure, privacy-preserving data sharing.
- Frontend: React (TypeScript) single-page application.
- Backend: NestJS (Node.js/TypeScript) REST API.
- Purpose: allow owners to publish encrypted datasets, permit authorized users to request access, run vetted computations (Python/R) on the data without exposing raw data, and return results.

##### High-level file-structure analysis
- Top-level directories:
– client/ → React app (src/api, components, contexts, pages).
– server/ → NestJS app (src/auth, computations, datasets, requests, users, tasks, vault, utils).
– server/run_computations/ → Python & R scripts invoked at runtime.
- Config & build scripts: vite.config.ts, nest-cli.json, tsconfig, package.json.
- Static assets: images/, events/ (presentations).
- Data stores indicated by server/.env.example (Postgres config) and dataset_files folders.

##### Key insights from README
- Architecture comprises:
– Client (React) → Backend API (NestJS) → Database (Postgres) + File Server (encrypted dataset files).
– Computation engine invokes Python/R scripts within a secure runtime.
– Uses AES-GCM encryption, client-server key exchange, JWT authentication, role-based guards.
– Background tasks (NestJS tasks module) for scheduled jobs.
– External service: SendGrid for email notifications.
- Database tables & relationships are fully described (users, datasets, variables, requests, computations, computation_runs, favorites).

##### Detail
- Next to file storage, note “AES-GCM encrypted at rest.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["React SPA (Client)"]:::frontend

    %% Backend API Gateway
    API["NestJS API Gateway"]:::backend

    Browser -->|"HTTPS, JWT"| API

    %% Backend Modules Subgraph
    subgraph "Backend Modules" 
        direction TB
        MainTS["main.ts"]:::backend
        AppModule["app.module.ts"]:::backend
        AuthModule["Auth Module"]:::backend
        DatasetsModule["Datasets Module"]:::backend
        RequestsModule["Requests Module"]:::backend
        ComputationsModule["Computations Module"]:::backend
        UsersModule["Users Module"]:::backend
        DashboardModule["Dashboard Module"]:::backend
        TasksModule["Background Tasks"]:::backend
        VaultModule["Vault Module"]:::legacy
        FileCryptoUtil["file-crypto.utils.ts"]:::utils
        FileUtil["file.utils.ts"]:::utils
        Entities["TypeORM Entities"]:::database
    end

    API -->|uses| MainTS
    API -->|uses| AppModule
    API -->|auth| AuthModule
    API -->|metadata| DatasetsModule
    API -->|workflow| RequestsModule
    API -->|compute metadata| ComputationsModule
    API -->|user mgmt| UsersModule
    API -->|metrics| DashboardModule
    API -->|schedules| TasksModule
    API -.->|legacy| VaultModule
    API -->|encrypt/decrypt| FileCryptoUtil
    API -->|file I/O| FileUtil
    API -->|CRUD| Entities

    %% Data Layer
    Postgres["PostgreSQL\n(users, datasets, requests,\ncomputations, computation_runs)"]:::storage
    FileStore["Encrypted File Storage\n(AES-GCM encrypted at rest)"]:::storage

    API -->|TypeORM| Postgres
    API -->|read/write files| FileStore

    %% Computation Runtime
    Runtime["Computation Runtime\n(Python/R scripts)"]:::runtime
    FileStore -->|temp decrypt| Runtime
    Runtime -->|output files| FileStore
    Runtime -->|results| API
    API -->|store runs| Postgres

    %% Background Tasks to DB
    TasksModule -->|scheduled jobs| Postgres

    %% External Services
    SendGrid["SendGrid (Email)"]:::external
    API -->|email notifications| SendGrid

    %% Click Events
    click Browser "https://github.com/cetorres/acsp4hr_project/tree/main/client/"
    click MainTS "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/main.ts"
    click AppModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/app.module.ts"
    click AuthModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/auth/auth.module.ts"
    click DatasetsModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/datasets/datasets.module.ts"
    click RequestsModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/requests/requests.module.ts"
    click ComputationsModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/computations/computations.module.ts"
    click UsersModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/users/users.module.ts"
    click DashboardModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/dashboard/dashboard.module.ts"
    click TasksModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/tasks/computations.tasks.module.ts"
    click VaultModule "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/vault/vault.module.ts"
    click FileCryptoUtil "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/utils/file-crypto.utils.ts"
    click FileUtil "https://github.com/cetorres/acsp4hr_project/blob/main/server/src/utils/file.utils.ts"
    click Entities "https://github.com/cetorres/acsp4hr_project/tree/main/server/src/users/entities/"
    click Entities "https://github.com/cetorres/acsp4hr_project/tree/main/server/src/datasets/entities/"
    click Entities "https://github.com/cetorres/acsp4hr_project/tree/main/server/src/requests/entities/"
    click Entities "https://github.com/cetorres/acsp4hr_project/tree/main/server/src/computations/entities/"
    click Runtime "https://github.com/cetorres/acsp4hr_project/tree/main/server/run_computations/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef backend fill:#d4edda,stroke:#28a745,color:#000;
    classDef storage fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef runtime fill:#f0f0f0,stroke:#6c757d,color:#000,stroke-dasharray: 5 5;
    classDef external fill:#ebedef,stroke:#adb5bd,color:#000;
    classDef legacy fill:#e2e3e5,stroke:#6c757d,color:#000,stroke-dasharray: 2 2;
    classDef utils fill:#d1ecf1,stroke:#17a2b8,color:#000;
    classDef database fill:#ffeeba,stroke:#ffcd39,color:#000,stroke:dotted;
```
