# openwallet-foundation-labs/dcql-ts architecture

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

- Interactive diagram: https://gitdiagram.com/openwallet-foundation-labs/dcql-ts
- Repository: https://github.com/openwallet-foundation-labs/dcql-ts

## Overview

##### Project type and purpose
- This is an open-source TypeScript library (DCQL) that implements the Digital Credentials Query Language.
- Its goal is to let client applications construct, parse, execute, and validate JSON-encoded queries over Verifiable Presentations.
- It is platform-agnostic and can run in Node.js, React Native, or browser environments.

##### File structure
- At the root you have monorepo files (.changeset, pnpm-workspace.yaml, turbo.json) and a single package under `/dcql`.
- Inside `/dcql/src` you see five major subdirectories:
- dcql-parser
- dcql-query
- dcql-query-result
- dcql-presentation
- dcql-error
- An `index.ts` re-exports the public API (DcqlQuery, DcqlQueryResult, etc.).
- There are tests alongside parser, query, and presentation modules.
- Config files (tsconfig.json, package.json) and CI/CD scripts (GitHub workflows) handle building, testing, and releasing.

##### README insights
- Confirms that this is a pure library, not a full application.
- Emphasizes JSON-encoded queries and validation of Verifiable Presentations.
- Mentions supported environments and contribution guidelines.

##### Main components & interactions
a. External “Client App”
- Imports DCQL package
- Builds or loads a JSON-formatted DCQL query
- Supplies Verifiable Presentations (VCs) to the library
- Receives a `DcqlQueryResult` indicating which credentials matched and any errors

- Parser module
- Parses JSON into an AST or internal model
- Query module
- Provides classes (`DcqlQuery`, m-models) for programmatic query construction
- Query-Result module
- Executes the query over input credentials; produces `DcqlQueryResult`
- Presentation module
- Validates/verifies presentations against query requirements
- Error module
- Defines error types (`DCErrors`) thrown at parsing or runtime

c. Data flow
1. Client → (JSON query) → Parser
2. Parser → (AST/model) → Query Executor
3. Executor + input credentials → Query-Result
4. Result → Presentation Validator → Final `DcqlQueryResult`
5. Errors bubble up via the Error module

##### Architectural patterns & design principles
- Modular separation by concern: parsing, query-building, execution, result processing, error handling.
- Public API layer (`index.ts`) hides internal module structure.
- Test harnesses alongside each module enforce correctness.
- CI/CD ensures build/test/release automation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client application
    ClientApp["Client Application"]:::external

    subgraph "DCQL Library"
        direction TB
        API["Public API (index.ts)"]:::api
        Parser["Parser Module"]:::parser
        Query["Query Module"]:::query
        Result["Query-Result Module"]:::result
        Presentation["Presentation Module"]:::presentation
        ErrorMod["Error Module"]:::error
        subgraph "Tests"
            direction TB
            ParserTests["Parser Tests"]:::tests
            QueryTests["Query Tests"]:::tests
        end
        CI["CI/CD Workflows"]:::ci
        Package["package.json"]:::meta
    end

    %% Data flow
    ClientApp -->|"imports API"| API
    ClientApp -->|"JSON Query"| Parser
    Parser -->|"AST/Model"| Result
    ClientApp -->|"Verifiable Presentations"| Result
    Result -->|"DcqlQueryResult"| Presentation
    Presentation -->|"Final Result"| ClientApp

    %% Error flow
    Parser -->|"parsing errors"| ErrorMod
    Result -->|"runtime errors"| ErrorMod
    ErrorMod -->|"throws errors"| ClientApp

    %% Click Events
    click Parser "https://github.com/openwallet-foundation-labs/dcql-ts/tree/main/dcql/src/dcql-parser"
    click Query "https://github.com/openwallet-foundation-labs/dcql-ts/tree/main/dcql/src/dcql-query"
    click Result "https://github.com/openwallet-foundation-labs/dcql-ts/tree/main/dcql/src/dcql-query-result"
    click Presentation "https://github.com/openwallet-foundation-labs/dcql-ts/tree/main/dcql/src/dcql-presentation"
    click ErrorMod "https://github.com/openwallet-foundation-labs/dcql-ts/tree/main/dcql/src/dcql-error"
    click API "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/dcql/src/index.ts"
    click Package "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/dcql/package.json"
    click ParserTests "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/dcql/src/dcql-parser/*.test.ts"
    click QueryTests "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/dcql/src/dcql-query/*.test.ts"
    click CI "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/openwallet-foundation-labs/dcql-ts/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef external fill:#eef,stroke:#333,stroke-width:1px;
    classDef api fill:#ffe4b5,stroke:#333,stroke-width:1px;
    classDef parser fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef query fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef result fill:#ffb6c1,stroke:#333,stroke-width:1px;
    classDef presentation fill:#dda0dd,stroke:#333,stroke-width:1px;
    classDef error fill:#f08080,stroke:#333,stroke-width:1px;
    classDef tests fill:#f0f0f0,stroke:#666,stroke-dasharray: 2 2;
    classDef ci fill:#e0ffe0,stroke:#333,stroke-width:1px;
    classDef meta fill:#ffffe0,stroke:#333,stroke-width:1px;
```
