# ski043/learn-orpc architecture

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

- Interactive diagram: https://gitdiagram.com/ski043/learn-orpc
- Repository: https://github.com/ski043/learn-orpc

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application (using the App Router), bootstrapped with create-next-app.
- It offers both REST-style endpoints under `app/api`, an RPC layer under `app/rpc` (backed by your custom `lib/orpc*` modules), and uses Prisma for database access.
- On the client side it demonstrates React-Query usage (`app/react-query-example`), custom UI components (`components/ui`), theming, and an authentication flow (`app/middlewares/auth.ts`, `app/router/auth.ts`).

##### Key File-Structure Insights
- Top-level “app” folder: Next.js 13+ App Router pages + serverless routes.
- app/page.tsx + layout.tsx: primary UI and layout.
- app/api/[[…rest]]/route.ts: catch-all REST endpoints.
- app/rpc/[[…rest]]/route.ts: catch-all RPC endpoints.
- app/middlewares/auth.ts: middleware for route protection.
- app/react-query-example: sample page to illustrate React-Query.
- app/router/*.ts: typed route definitions for client side.
- app/schemas: Zod schemas for auth, todo, user.
- “components” folder: reusable UI atoms/molecules, plus a simple-todo component.
- “lib” folder:
- db.ts – Prisma client.
- orpc.ts / orpc.server.ts – client/server glue for RPC.
- providers.tsx – React context providers (AuthProvider, ThemeProvider).
- utils.ts – misc helpers.
- Prisma: `prisma/schema.prisma` defines the data model.
- Config/build files: next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs.

a. Frontend (Browser / Next.js React):
- Pages & Layout (app/page.tsx, layout.tsx)
- UI Components (components/ui/*, components/todo)
- React Query & ORPC Client (lib/orpc.ts, app/react-query-example)
- Providers (AuthProvider, ThemeProvider)
b. Next.js Server (Vercel lambdas or Node server):
- Routing Layer (App Router)
- REST API Endpoints (app/api/…)
- RPC Endpoints (app/rpc/…)
- Middleware (app/middlewares/auth.ts)
- Schema validation (app/schemas via Zod)
c. Database Layer:
- Prisma Client (lib/db.ts)
- Underlying database (PostgreSQL, MySQL, etc.)
d. External Services (if any):
- Authentication provider (JWT or session store)
- Monitoring/instrumentation (instrumentation.ts)

##### Relationships & Data Flow
- Browser sends SSR/SSG page requests to Next.js Server.
- For mutations/queries:
- React Query hooks → REST API routes (app/api)
- ORPC Client → RPC routes (app/rpc)
- Server middleware authenticates requests, validates payloads (Zod schemas), then calls Prisma client.
- Prisma executes SQL against the database and returns results.
- Server responds with JSON or rendered HTML, back to the browser.

##### Architectural Patterns & Principles
- Feature-oriented folder structure under “app” (App Router).
- Separation of concerns: UI components vs. data layer vs. routing.
- Typed contracts: Zod schemas + TypeScript for end-to-end type safety.
- Hybrid data-fetching strategies: SSR pages, REST, RPC, React-Query caching.
- Infrastructure as code: Next.js configuration, Prisma schema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser + React)"
        direction TB
        Pages["Pages & Layout"]:::frontend
        UI["UI Components"]:::ui
        ReactQuery["React-Query Example"]:::frontend
        ReactQueryForm["TanStack Form Component"]:::frontend
        ORPCClient["ORPC Client"]:::rpc
        ORPCServer["ORPC Server Glue"]:::rpc
        Providers["React Context Providers"]:::frontend
        TypedRoutes["Typed Routes"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Server (Lambdas)"
        direction TB
        Routing["App Router"]:::server
        Middleware["Auth Middleware"]:::middleware
        REST["REST API Endpoints"]:::api
        RPC["RPC API Endpoints"]:::rpc
        subgraph "Zod Schemas"
            direction TB
            AuthSchema["auth.ts"]:::schema
            TodoSchema["todo.ts"]:::schema
            UserSchema["user.ts"]:::schema
        end
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        PrismaClient["Prisma Client"]:::db
        PrismaSchema["Prisma Schema"]:::schema
        Database["Database"]:::db
    end

    %% Relationships
    User["User"]:::external --> Pages
    Pages -->|renders via SSR/SSG| Routing
    Pages -->|uses| UI
    UI -->|wrapped by| Providers
    Pages -->|data-fetch| ReactQuery
    ReactQuery -->|uses form| ReactQueryForm
    ReactQuery -->|HTTP| REST
    UI -->|invokes| ORPCClient
    ORPCClient -->|JSON-RPC| RPC
    ORPCServer -->|binds to| RPC
    TypedRoutes -->|typed links| Pages

    Routing --> Middleware
    Middleware --> REST
    Middleware --> RPC
    REST --> AuthSchema
    REST --> TodoSchema
    REST --> UserSchema
    RPC --> AuthSchema
    RPC --> TodoSchema
    RPC --> UserSchema
    AuthSchema --> PrismaClient
    TodoSchema --> PrismaClient
    UserSchema --> PrismaClient
    PrismaClient --> PrismaSchema
    PrismaClient --> Database

    %% Click events
    click Pages "https://github.com/ski043/learn-orpc/blob/main/app/page.tsx"
    click UI "https://github.com/ski043/learn-orpc/blob/main/components/ui/button.tsx"
    click ReactQuery "https://github.com/ski043/learn-orpc/blob/main/app/react-query-example/page.tsx"
    click ReactQueryForm "https://github.com/ski043/learn-orpc/blob/main/app/react-query-example/_components/tanstack-form.tsx"
    click ORPCClient "https://github.com/ski043/learn-orpc/blob/main/lib/orpc.ts"
    click ORPCServer "https://github.com/ski043/learn-orpc/blob/main/lib/orpc.server.ts"
    click Providers "https://github.com/ski043/learn-orpc/blob/main/lib/providers.tsx"
    click REST "https://github.com/ski043/learn-orpc/blob/main/app/api/[[...rest]]/route.ts"
    click RPC "https://github.com/ski043/learn-orpc/blob/main/app/rpc/[[...rest]]/route.ts"
    click Middleware "https://github.com/ski043/learn-orpc/blob/main/app/middlewares/auth.ts"
    click AuthSchema "https://github.com/ski043/learn-orpc/blob/main/app/schemas/auth.ts"
    click TodoSchema "https://github.com/ski043/learn-orpc/blob/main/app/schemas/todo.ts"
    click UserSchema "https://github.com/ski043/learn-orpc/blob/main/app/schemas/user.ts"
    click PrismaClient "https://github.com/ski043/learn-orpc/blob/main/lib/db.ts"
    click PrismaSchema "https://github.com/ski043/learn-orpc/blob/main/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef server fill:#ffebee,stroke:#b71c1c,color:#880e4f
    classDef api fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef rpc fill:#fff3e0,stroke:#bf360c,color:#e65100
    classDef db fill:#e3f2fd,stroke:#0d47a1,color:#1565c0
    classDef schema fill:#f3e5f5,stroke:#4a148c,color:#6a1b9a
    classDef middleware fill:#fffde7,stroke:#f9a825,color:#f57f17
    classDef ui fill:#f1f8e9,stroke:#33691e,color:#558b2f
    classDef external fill:#ffffff,stroke:#000000,color:#000000,stroke-dasharray: 2 2
```
