# paras-ecosystem/paras-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/paras-ecosystem/paras-compiler
- Repository: https://github.com/paras-ecosystem/paras-compiler

## Overview

ParaS is a SYCL 2020 compiler and runtime for portable CPU and NVIDIA GPU execution. The principal workflow is a developer invoking `parascc` on SYCL source, then running the resulting program on a supported device. The tree separates compiler-driver transformations, SYCL API types, and host/GPU execution backends. The excerpts show handler dispatch into GPU execution and threadpool command-group submission; many compiler and runtime implementation files were not sampled, so their internal call relationships are not asserted.

Main entry points: [`include/kem_gpu/gpu_threadpool.hpp`](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/gpu_threadpool.hpp) (GPU threadpool), [`include/sycl/queue.hpp`](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/queue.hpp) (Queue API), [`include/sycl/handler.hpp`](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/handler.hpp) (Command handler), [`include/kem/threadpool.hpp`](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem/threadpool.hpp) (CPU threadpool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler frontend"]
  node_parascc["parascc driver<br/>[driver.cpp]"]
  node_ast_handlers["AST handlers"]
  node_preprocessor["Preprocessor<br/>[Preprocessor.cpp]"]
end

subgraph group_api["SYCL API"]
  node_queue["Queue API<br/>[queue.hpp]"]
  node_handler["Command handler<br/>[handler.hpp]"]
  node_device_context["Device and context<br/>[device.hpp]"]
  node_work_items["Work-item types<br/>[item.hpp]"]
  node_ranges["Range types<br/>[range.hpp]"]
end

subgraph group_execution["Execution backends"]
  node_cpu_pool["CPU threadpool<br/>[threadpool.hpp]"]
  node_host_groups["Host group runtime"]
  node_gpu_pool["GPU threadpool<br/>[gpu_threadpool.hpp]"]
  node_gpu_handler_impl["GPU handler dispatch<br/>[handler_impl.hpp]"]
  node_gpu_kernels["GPU range execution"]
end

subgraph group_discovery["Device discovery"]
  node_device_detection["GPU detection<br/>[gpu_detection.cpp]"]
  node_device_runtime["Device runtime<br/>[device.cpp]"]
end

node_developer(("SYCL developer"))
node_cuda["NVIDIA CUDA"]

node_developer -->|"compiles source"| node_parascc
node_parascc -->|"targets CPU/GPU"| node_developer
node_queue -->|"uses device APIs"| node_device_context
node_queue -->|"uses command handler"| node_handler
node_handler -->|"uses work items"| node_work_items
node_handler -->|"uses ranges"| node_ranges
node_cpu_pool -->|"constructs from queue"| node_queue
node_cpu_pool -->|"runs command group"| node_handler
node_gpu_pool -->|"creates queue pool"| node_queue
node_gpu_handler_impl -->|"dispatches kernels"| node_gpu_pool
node_gpu_pool -->|"uses range executor"| node_gpu_kernels
node_device_runtime -->|"uses GPU detection"| node_device_detection
node_device_detection -->|"queries device APIs"| node_device_runtime
node_gpu_pool -.->|"executes on"| node_cuda

click node_parascc "https://github.com/paras-ecosystem/paras-compiler/blob/main/src/driver/driver.cpp"
click node_ast_handlers "https://github.com/paras-ecosystem/paras-compiler/tree/main/src/driver"
click node_preprocessor "https://github.com/paras-ecosystem/paras-compiler/blob/main/src/driver/Preprocessor.cpp"
click node_queue "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/queue.hpp"
click node_handler "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/handler.hpp"
click node_device_context "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/device.hpp"
click node_work_items "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/item.hpp"
click node_ranges "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/range.hpp"
click node_cpu_pool "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem/threadpool.hpp"
click node_host_groups "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem/host_group_runtime.hpp"
click node_gpu_pool "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/gpu_threadpool.hpp"
click node_gpu_handler_impl "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/handler_impl.hpp"
click node_gpu_kernels "https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/gpu_threadpool_execute_nd_range_1D.hpp"
click node_device_detection "https://github.com/paras-ecosystem/paras-compiler/blob/main/src/pruntime_system/gpu_detection.cpp"
click node_device_runtime "https://github.com/paras-ecosystem/paras-compiler/blob/main/src/pruntime_system/device.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parascc,node_ast_handlers,node_preprocessor toneBlue
class node_queue,node_handler,node_device_context,node_work_items,node_ranges toneAmber
class node_cpu_pool,node_host_groups,node_gpu_pool,node_gpu_handler_impl,node_gpu_kernels toneMint
class node_device_detection,node_device_runtime toneRose
class node_developer,node_cuda toneIndigo
```

## Components

### Compiler frontend

- [parascc driver](https://github.com/paras-ecosystem/paras-compiler/blob/main/src/driver/driver.cpp): `src/driver/driver.cpp`
- [AST handlers](https://github.com/paras-ecosystem/paras-compiler/tree/main/src/driver): `src/driver`
- [Preprocessor](https://github.com/paras-ecosystem/paras-compiler/blob/main/src/driver/Preprocessor.cpp): `src/driver/Preprocessor.cpp`

### SYCL API

- [Queue API](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/queue.hpp): `include/sycl/queue.hpp`
- [Command handler](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/handler.hpp): `include/sycl/handler.hpp`
- [Device and context](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/device.hpp): `include/sycl/device.hpp`
- [Work-item types](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/item.hpp): `include/sycl/item.hpp`
- [Range types](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/sycl/range.hpp): `include/sycl/range.hpp`

### Execution backends

- [CPU threadpool](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem/threadpool.hpp): `include/kem/threadpool.hpp`
- [Host group runtime](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem/host_group_runtime.hpp): `include/kem/host_group_runtime.hpp`
- [GPU threadpool](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/gpu_threadpool.hpp): `include/kem_gpu/gpu_threadpool.hpp`
- [GPU handler dispatch](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/handler_impl.hpp): `include/kem_gpu/handler_impl.hpp`
- [GPU range execution](https://github.com/paras-ecosystem/paras-compiler/blob/main/include/kem_gpu/gpu_threadpool_execute_nd_range_1D.hpp): `include/kem_gpu/gpu_threadpool_execute_nd_range_1D.hpp`

### Device discovery

- [GPU detection](https://github.com/paras-ecosystem/paras-compiler/blob/main/src/pruntime_system/gpu_detection.cpp): `src/pruntime_system/gpu_detection.cpp`
- [Device runtime](https://github.com/paras-ecosystem/paras-compiler/blob/main/src/pruntime_system/device.cpp): `src/pruntime_system/device.cpp`

### Other components

- **SYCL developer**
- **NVIDIA CUDA**

## Connections

- SYCL developer → parascc driver: compiles source (evidence: `README.md`)
- parascc driver → SYCL developer: targets CPU/GPU (evidence: `README.md`)
- Queue API → Device and context: uses device APIs (evidence: `include/sycl/queue.hpp`)
- Queue API → Command handler: uses command handler (evidence: `include/sycl/queue.hpp`)
- Command handler → Work-item types: uses work items (evidence: `include/sycl/handler.hpp`)
- Command handler → Range types: uses ranges (evidence: `include/sycl/handler.hpp`)
- CPU threadpool → Queue API: constructs from queue (evidence: `include/kem/threadpool.hpp`)
- CPU threadpool → Command handler: runs command group (evidence: `include/kem/threadpool.hpp`)
- GPU threadpool → Queue API: creates queue pool (evidence: `include/kem_gpu/gpu_threadpool.hpp`)
- GPU handler dispatch → GPU threadpool: dispatches kernels (evidence: `include/kem_gpu/handler_impl.hpp`)
- GPU threadpool → GPU range execution: uses range executor (evidence: `include/kem_gpu/gpu_threadpool.hpp`)
- Device runtime → GPU detection: uses GPU detection (evidence: `src/pruntime_system/device.cpp`)
- GPU detection → Device runtime: queries device APIs (evidence: `src/pruntime_system/gpu_detection.cpp`)
- GPU threadpool → NVIDIA CUDA: executes on (evidence: `README.md`)
