# canyon-project/canyon architecture

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

- Interactive diagram: https://gitdiagram.com/canyon-project/canyon
- Repository: https://github.com/canyon-project/canyon

## Overview

Based on our analysis of the file tree and the README, Canyon is a JavaScript code coverage collection platform that gathers coverage data during end-to-end tests. The project is clearly divided into multiple parts:
- Plugins that integrate with various CI tools (for example, babel-plugin-canyon, swc-plugin-canyon, and others found under the plugins directory) to collect environment information.
- A backend API service (located within packages/canyon-backend) whose role is to ingest, process, and store coverage data. This module uses frameworks like NestJS (evident from files like nest-cli.json and typical NestJS structure in the backend folder), GraphQL (you see .gql schemas/resolvers and Apollo-style queries), and Prisma for database interactions.
- Data processing modules (packages/canyon-data and packages/canyon-map) that format and map the raw coverage details into processed reports.
- A front-end dashboard and platform (packages/canyon-platform) that displays coverage reports and integrates with the back-end. The front-end exhibits a modern web stack using React (notice TSX files, NextJS/Vite configurations in examples, etc.) and extended support for internationalization (multiple languages under the website folder).
- Additional tools (like canyon-uploader and canyon-extension, under the tools directory) that help with uploading coverage data and offering browser integrations.

a. Coverage Collection Plugins – Representing the plugins (Babel, SWC, etc.) as external modules that hook into different parts of the CI/CD process.
b. Coverage Uploader – A specialized tool/service (for example, canyon-uploader) that relays the collected data.
c. API & Processing Service – The backend API (packages/canyon-backend) that receives data from the uploader/plugins, along with processing units that include coverage data formatting (canyon-data) and map generation (canyon-map). Also indicate modules for authentication and code change tracking (as seen in auth and codechange directories).
d. Database – While not directly mentioned as a db product, the presence of Prisma and migrations suggests a database that is used to store coverage, project, and user data.
e. Report Front-end Application – The web front-end (canyon-platform) that provides visualization of the coverage reports, integrated with GraphQL endpoints.
f. External Integrations – Nodes for Git providers (e.g., GitLab adapter) and other external services that support OAuth and environment variable injection.

b. API interacting with the database for storing code coverage and project records.
c. Processed data flow from the API to the front-end dashboard where users view reports.
d. Bi-directional connections where applicable (for example, authentication feedback between the front-end and the backend).

##### Architectural patterns/design details
a. Microservices or modular monolith segmentation: Note the separation between data collection, the API (which takes advantage of NestJS’s module system), and the front-end.
b. Clear segregation between the presentation (front-end) and business logic (back-end API) layers.
c. Use of GraphQL as the API contract between the front-end and the backend (noted by schema files and resolvers).

##### Technologies, frameworks, and libraries
a. Languages: JavaScript/TypeScript and parts in Rust (plugins like swc-plugin-canyon).
b. Frameworks: NestJS (backend), Next.js/Vite (front-end examples/platform), GraphQL.
c. Database integration through Prisma.
d. Build and deployment tools such as Docker, GitHub Actions workflows, and various configuration files across the repository.
e. Supporting libraries for testing (e.g., Jest, Vitest, Mocha) because of the different reporter examples provided.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Collection Layer
    subgraph "Data Collection Layer"
        BP["Babel Plugin Canyon"]:::plugins
        SP["SWC Plugin Canyon"]:::plugins
        CU["Coverage Uploader"]:::uploader
    end

    %% Backend Service Layer
    subgraph "Backend Service Layer"
        API["API Service (NestJS/GraphQL)"]:::backend
        subgraph "Data Processing Modules"
            CD["Canyon Data"]:::processing
            CM["Canyon Map"]:::processing
        end
        EI["GitLab Adapter"]:::integrations
        DB["Database (Prisma)"]:::database
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Report Front-end Application"]:::frontend
    end

    %% Connections from Data Collection to API Service
    BP -->|"sends_coverage"| API
    SP -->|"sends_coverage"| API
    CU -->|"uploads_coverage"| API

    %% API Service interactions
    API -->|"processes_data"| CD
    API -->|"processes_data"| CM
    API -->|"stores_data"| DB
    API -->|"exposes_API"| FE
    API <-->|"auth_integration"| EI

    %% Click Events
    click BP "https://github.com/canyon-project/canyon/tree/main/plugins/babel-plugin-canyon"
    click SP "https://github.com/canyon-project/canyon/tree/main/plugins/swc-plugin-canyon"
    click CU "https://github.com/canyon-project/canyon/tree/main/tools/canyon-uploader"
    click API "https://github.com/canyon-project/canyon/tree/main/packages/canyon-backend"
    click CD "https://github.com/canyon-project/canyon/tree/main/packages/canyon-data"
    click CM "https://github.com/canyon-project/canyon/tree/main/packages/canyon-map"
    click FE "https://github.com/canyon-project/canyon/tree/main/packages/canyon-platform"
    click EI "https://github.com/canyon-project/canyon/blob/main/packages/canyon-backend/src/adapter/gitlab.adapter.ts"

    %% Styles
    classDef plugins fill:#f9d5e5,stroke:#d87093,stroke-width:2px;
    classDef uploader fill:#fff3cd,stroke:#ffb300,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#99ccff,stroke-width:2px;
    classDef processing fill:#e0f7e9,stroke:#a3c293,stroke-width:2px;
    classDef frontend fill:#d4edda,stroke:#91c788,stroke-width:2px;
    classDef integrations fill:#d1c4e9,stroke:#9575cd,stroke-width:2px;
    classDef database fill:#ffe0b2,stroke:#ffb74d,stroke-width:2px;
```
