# raviqqe/onerpc architecture

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

- Interactive diagram: https://gitdiagram.com/raviqqe/onerpc
- Repository: https://github.com/raviqqe/onerpc

## Overview

##### Project Overview and Type
- oneRPC is a minimal RPC library that “converts” a server-side function with type (input: T) => Promise<S> into a HTTP-compatible request handler (Request) => Promise<Response>.
- It is designed to provide type safety and smooth client-server communication for serverless environments such as Next.js Route Handlers and AWS Lambda.
- The project is a library (with demonstration examples in the “examples” directory) that abstracts the RPC pattern with adapters and middleware.

##### Components from the File Structure
- Top-Level Directories and Files
- The root has configuration files (.cspell.json, package.json, tsconfig.json, eslint.config.js, etc.), alongside the README and LICENSE.
- The “src” directory holds the core logic of oneRPC (client, main functions, error handling, validation, middleware, options, and utilities).
- The “src/adapter” folder shows that there is a dedicated adapter for AWS Lambda (“aws-lambda.ts”), indicating support for different runtime environments.
- The “src/middleware” directory (and related tests) builds the processing chain for request/response transformation (e.g., “etag.ts” and “utility.ts”).
- The “examples/aws” folder provides a concrete AWS Lambda implementation with its own project files and tests, illustrating practical usage.

##### Main Architectural Components
- Client Component
- Represented by files like “src/client.ts” which provides the RPC invocation functionality from the client side.
- RPC Server-side Handler (Core Logic)
- The “src/main.ts”, “src/error.ts”, “src/validation.ts”, “src/options.ts”, and “src/utility.ts” files form the core engine that wraps a server function (with type (T) => Promise<S>) into a Request handler.
- Middleware Chain
- The middleware components in “src/middleware” (for example, “etag.ts” and “utility.ts”) indicate that all requests/responses can be intercepted or modified.
- Environment Adapters
- The “src/adapter/aws-lambda.ts” is a key adapter that allows the oneRPC core to be deployed as an AWS Lambda function.
- Similarly, the README code snippet shows usage for Next.js Route Handlers—thus, while there might not be an explicit “adapter” for Next.js in the file tree, it is supported by design.
- External Integration Points
- Since additional routing/rpc conversion is delegated to external frameworks (e.g., Next.js or AWS), represent these as “External HTTP Framework/Infrastructure” components that feed into the adapter layer.

##### Relationships and Data Flow
- Client → RPC Call: The client component (using “src/client.ts”) initiates a remote function call from the client side.
- Request Routing via Environment Adapter: The call first reaches an environment-specific adapter (for instance, the AWS Lambda adapter shown in “src/adapter/aws-lambda.ts” or handled via Next.js routing in a Route Handler).
- Middleware Processing: Before reaching the core function, the request is processed through the middleware chain (as defined in “src/middleware”), which can handle concerns like header manipulation (e.g., ETag handling) and utility functions.
- Core RPC Function: The main processing occurs in “src/main.ts” and is supported by validation, error handling, and options configurations.
- Response Path: Once the core function processes the request, the response is sent back through the same middleware chain (if needed) and then returns to the client, converting promises and streaming responses as JSON Lines if applicable.

##### Architectural Design Principles to Emphasize
- Separation of Concerns: Clearly separate the client invocation, middleware processing, RPC core logic, and environment-specific adapters.
- Flexibility and Extensibility: The design allows plugging in new adapters for other environments due to the adapter pattern seen here.
- Minimal Dependencies & HTTP Friendliness: Emphasize that the library leverages Web APIs directly, ensuring portability across platforms like Node.js, Deno, and edge runtimes.
- Type-Safe Communication: Include that the use of TypeScript types ensures compile-time safety for both requests and responses.

##### Final Recommendations
- Clearly label every component, such as “Client”, “AWS Lambda Adapter”, “Middleware (ETag, Utility)”, “RPC Core”, “Validation”, and “Error Handling”.
- Annotations about TypeScript and the design goals (type safety, minimal dependencies, serverless-first) to inform about key non-functional design principles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Cl["Client (Type-safe RPC Call)"]:::client
    end

    %% Environment Adapters
    subgraph "Environment Adapters"
        AL["AWS Lambda Adapter"]:::adapter
        NX["Next.js Route Handler"]:::adapter
    end

    %% Middleware Chain
    subgraph "Middleware Chain"
        EM["ETag Middleware"]:::middleware
        UM["Utility Middleware"]:::middleware
        EMT["ETag Middleware Test"]:::middleware
    end

    %% RPC Core Engine
    subgraph "RPC Core Engine"
        Core["RPC Core Main"]:::core
        Err["Error Handling"]:::core
        Val["Validation"]:::core
        Opt["Options"]:::core
        UCore["Utility in Core"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        AWSExp["AWS Lambda Example App"]:::external
    end

    %% Flow Connections
    Cl -->|"RPC_request"| AL
    Cl -->|"RPC_request"| NX

    AL -->|"pre_process"| EM
    NX -->|"pre_process"| EM

    EM -->|"chain"| UM
    UM -->|"validate"| Core

    Core -->|"handle_errors"| Err
    Core -->|"validate_input"| Val
    Core -->|"apply_options"| Opt
    Core -->|"use_utilities"| UCore

    Core -->|"RPC_response"| UM
    UM -->|"post_process"| EM
    EM -->|"finalize"| AL
    AL -->|"send_response"| Cl

    %% External AWS Example Integration
    AWSExp -->|"demonstrates"| AL

    %% Click Events
    click Cl "https://github.com/raviqqe/onerpc/blob/main/src/client.ts"
    click Core "https://github.com/raviqqe/onerpc/blob/main/src/main.ts"
    click Err "https://github.com/raviqqe/onerpc/blob/main/src/error.ts"
    click Val "https://github.com/raviqqe/onerpc/blob/main/src/validation.ts"
    click Opt "https://github.com/raviqqe/onerpc/blob/main/src/options.ts"
    click UCore "https://github.com/raviqqe/onerpc/blob/main/src/utility.ts"
    click EM "https://github.com/raviqqe/onerpc/blob/main/src/middleware/etag.ts"
    click UM "https://github.com/raviqqe/onerpc/blob/main/src/middleware/utility.ts"
    click EMT "https://github.com/raviqqe/onerpc/blob/main/src/middleware/etag.test.ts"
    click AL "https://github.com/raviqqe/onerpc/blob/main/src/adapter/aws-lambda.ts"
    click AWSExp "https://github.com/raviqqe/onerpc/tree/main/examples/aws"
    %% Additional example specific files
    click AWSExp "https://github.com/raviqqe/onerpc/blob/main/examples/aws/src/main.ts"
    click AWSExp "https://github.com/raviqqe/onerpc/blob/main/examples/aws/src/lambda/square.ts"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef adapter fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef middleware fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef core fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
