# krnl-labs/my-krnl-app architecture

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

- Interactive diagram: https://gitdiagram.com/krnl-labs/my-krnl-app
- Repository: https://github.com/krnl-labs/my-krnl-app

## Overview

##### Project type and purpose
- This is a Next.js-based single-page application (SPA) with React 18+ and the App Router.
- It bundles on-chain logic (“kernels”) under `src/components/kernels/onchain` and an Ethereum smart contract ABI in `src/mainContract/abi.json`.
- In effect it’s a front-end dApp: a component-based UI that interacts with an Ethereum (or EVM-compatible) network via JSON-RPC, using environment-supplied endpoints and contract addresses.

##### File structure
- Top-level config:
– `.env` / `.env.example`: RPC URL, contract address, API keys
– `next.config.ts`, `postcss.config.mjs`, `eslint.config.mjs`, `tsconfig.json`
- Application code under `src/`:
– `app/`: Next.js pages (`layout.tsx`, `page.tsx`), global CSS
– `components/`: reusable UI pieces
– `components/kernels/onchain/<chainId>/`: per-chain on-chain logic (each has `config.ts` and `index.ts`)
- `src/mainContract/abi.json`: the ABI for interacting with a deployed smart contract
- `public/`: static assets served at runtime

##### Extracting insights from README
- Bootstrapped with Create-Next-App, uses `next/font` for optimized fonts.
- No backend folder or API routes—logic runs client-side or via Next.js server (SSR/SSG).
- Deployment target is Vercel (serverless), but could be any Next.js host.

##### Main components
a. User’s Browser (Client) – React SPA served by Next.js
b. Next.js Server / Build (SSG/SSR/runtime)
c. Static Asset Store (`public/`, CSS, fonts)
d. On-chain Kernels (dynamic modules under `components/kernels/onchain`)
e. Smart Contract ABI Module (`src/mainContract/abi.json`)
f. JSON-RPC Provider / Ethereum Network (external service)
g. Environment Variables Store (.env)
h. Deployment Platform (Vercel or equivalent)

##### Relationships and data flow
- Client → Next.js Server: initial HTML + JS bundle request
- Next.js Server → Static Store: fetch CSS, images, fonts
- Client/Server → On-chain Kernel: at runtime the SPA loads the appropriate kernel module (based on chainId)
- Kernel & ABI Module → JSON-RPC provider endpoint (ENV.RPC_URL): sends read/write calls to the smart contract
- Ethereum Network → Response → Kernel → React State → UI update
- Environment variables injected at build/runtime into Next.js via `next.config.ts`

##### Architectural patterns & design principles
- Component-based UI (React)
- Dynamic module loading for pluggable on-chain kernels
- Separation of concerns: UI vs. chain integration vs. contract spec
- SSR/SSG for performance, CSR for interactivity
- 12-factor principle: config via environment variables

##### Final checklist for the engineer
- Break the system into at least these layers:
– Client (browser)
– Next.js (SSG/SSR + CSR)
– UI Components & Kernels
– Smart Contract Interface
– Blockchain Network
- Hosting/deployment (Vercel) and environment management.
- Keep it uncluttered: group similar components, label connectors, and use consistent styling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        Browser["User’s Browser (React SPA)"]:::frontend
    end

    %% Next.js Server / Build Layer
    subgraph "Next.js Server / Build (SSG/SSR + CSR)"
        NextJS["Next.js Server / Build"]:::frontend
    end

    %% Static Assets
    Assets["Static Asset Store\n(public/, CSS, fonts)"]:::static

    %% UI Components & Kernels Layer
    subgraph "UI Components & On-chain Kernels"
        UI["Reusable UI Components"]:::frontend
        Kernels["On-chain Kernels\n(src/components/kernels/onchain)"]:::onchain
    end

    %% Smart Contract Interface
    SC["Smart Contract ABI Module\n(src/mainContract/abi.json)"]:::onchain

    %% Blockchain Network
    RPC["Ethereum JSON-RPC Node\n(External Service)"]:::db

    %% Environment Variables
    Env["Environment Variables\n(.env, .env.example)"]:::env

    %% Deployment Platform
    Deploy["Deployment Platform (Vercel)"]:::external

    %% Connections
    Browser -->|"Request HTML+JS Bundle"| NextJS
    NextJS -->|"Serves CSS, Images, Fonts"| Assets
    Browser -->|"Loads UI Components"| UI
    Browser -->|"Loads Kernel Modules"| Kernels
    Kernels -->|"Reads ABI & Calls RPC"| RPC
    SC -->|"Provides ABI to Kernels"| Kernels
    RPC -->|"Returns Data"| Kernels
    Env -.->|"Injects RPC_URL & CONTRACT_ADDR"| NextJS
    Deploy -->|"Hosts Application"| NextJS

    %% Click Events
    click Browser "https://github.com/krnl-labs/my-krnl-app/blob/main/src/app/page.tsx"
    click Browser "https://github.com/krnl-labs/my-krnl-app/blob/main/src/app/layout.tsx"
    click NextJS "https://github.com/krnl-labs/my-krnl-app/blob/main/next.config.ts"
    click NextJS "https://github.com/krnl-labs/my-krnl-app/blob/main/tsconfig.json"
    click NextJS "https://github.com/krnl-labs/my-krnl-app/tree/main/src/app/"
    click Assets "https://github.com/krnl-labs/my-krnl-app/tree/main/public/"
    click Assets "https://github.com/krnl-labs/my-krnl-app/blob/main/src/app/globals.css"
    click UI "https://github.com/krnl-labs/my-krnl-app/tree/main/src/components/"
    click Kernels "https://github.com/krnl-labs/my-krnl-app/blob/main/src/components/kernels/onchain/337/config.ts"
    click Kernels "https://github.com/krnl-labs/my-krnl-app/blob/main/src/components/kernels/onchain/337/index.ts"
    click SC "https://github.com/krnl-labs/my-krnl-app/blob/main/src/mainContract/abi.json"
    click Env "https://github.com/krnl-labs/my-krnl-app/blob/main/.env"
    click Env "https://github.com/krnl-labs/my-krnl-app/blob/main/.env.example"
    click Deploy "https://github.com/krnl-labs/my-krnl-app/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef onchain fill:#D6F5D6,stroke:#2c662d,color:#2c662d;
    classDef db fill:#FFF5BA,stroke:#8a6d3b,color:#8a6d3b;
    classDef static fill:#E0E0E0,stroke:#444444,color:#444444,stroke-dasharray: 5 5;
    classDef env fill:#F3E5F5,stroke:#a64ca6,color:#a64ca6,stroke-dasharray: 2 2;
    classDef external fill:#E8E8E8,stroke:#666666,color:#666666;
```
