# midnightntwrk/example-bboard architecture

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

- Interactive diagram: https://gitdiagram.com/midnightntwrk/example-bboard
- Repository: https://github.com/midnightntwrk/example-bboard

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized application (DApp) composed of:
– A Compact smart contract (“contract” package) that enforces bulletin‐board rules on-chain.
– A shared API library (“api” package) for interacting with the contract.
– Two clients:
- bboard-cli – a Node.js CLI tool to deploy, post, and remove messages.
- bboard-ui – a React/Vite web UI for the same operations in the browser.
– External services: a Proof Server (local or remote) and a blockchain/testnet.

##### Break Out Top-Level Components
A. Contract
– Source files (contract/src/...).
– Compiler (Compact Compiler → generates on-chain bytecode / schema).
– Tests & simulator (contract/src/test).
B. API Library
– Entry point (api/src/index.ts).
– Common types and utility modules.
– Exposed methods for deploy(), postMessage(), takeDown().
C. CLI Client
– Launchers for various modes (standalone, testnet-local, testnet-remote).
– Configuration files (proof-server.yml).
– Uses the API library to orchestrate contract calls.
D. Web UI
– React app (bboard-ui/src).
– Contexts & hooks (DeployedBoardContext).
– Theming and layout components.
– Imports the API library in the browser bundle.
E. External Services
– Proof Server (verifies zero-knowledge proofs).
– Blockchain network (local standalone chain or remote testnet).

##### Relationships and Data Flows
– CLI/UI → API library → Proof Server → Blockchain.
– Blockchain → Contract bytecode + on-chain state → API library returns responses → CLI/UI.
– For standalone mode, show a “Local Proof Server + Local Blockchain” cluster.
– For testnet mode, show “Remote Proof Server” and “Testnet” as separate endpoints.

##### Architectural Patterns & Design Principles
– Monorepo modularity: four sibling packages (api, contract, bboard-cli, bboard-ui).
– Separation of concerns: contract logic vs. client interfaces vs. shared API.
– Reusability: both UI and CLI depend on the same API library.
– Pluggable deployment modes: standalone vs. testnet-local vs. testnet-remote.

##### Technologies, Frameworks & Libraries
– Smart-contract language: Compact (see badge in README).
– Language: TypeScript throughout (tsconfig.json in each package).
– Build tools: npm, vite (UI), vitest (CLI tests), ts-compiler.
– Linting/formatting: ESLint, Prettier configs.
– CI/CD: GitHub workflows (ci.yaml, checkmarx.yaml).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Workspace
    subgraph "Monorepo Workspace"
        direction TB
        subgraph "Contract Package" 
            direction TB
            C1["Source Files"]:::package
            C2["Compact Compiler"]:::package
            C3["Tests & Simulator"]:::package
        end
        subgraph "API Library"
            direction TB
            A1["api/src/index.ts"]:::package
            A2["Common Types & Utils"]:::package
        end
        subgraph "CLI Client (bboard-cli)" 
            direction TB
            CLI1["Entry: bboard-cli/src/index.ts"]:::client
            CLI2["Launchers"]:::client
            CLI3["Config Files"]:::client
        end
        subgraph "Web UI (bboard-ui)"
            direction TB
            UI1["React App Entry"]:::client
            UI2["Components & Layout"]:::client
            UI3["Contexts & Hooks"]:::client
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PS["Proof Server"]:::service
        BC["Blockchain / Testnet"]:::onchain
    end

    %% Relationships
    CLI1 -->|"uses API"| A1
    UI1 -->|"uses API"| A1
    A1 -->|"proofRequest"| PS
    PS -->|"zk-proof"| A1
    A1 -->|"RPC"| BC
    BC -->|"on-chain state"| A1
    C2 -->|"compiles to bytecode"| BC

    %% Click Events for Contract Package
    click C1 "https://github.com/midnightntwrk/example-bboard/tree/main/contract/src"
    click C1 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/index.ts"
    click C1 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/bboard.compact"
    click C3 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/test/bboard.test.ts"
    click C3 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/test/bboard-simulator.ts"
    click C3 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/test/utils.ts"
    click C1 "https://github.com/midnightntwrk/example-bboard/blob/main/contract/src/witnesses.ts"

    %% Click Events for API Library
    click A1 "https://github.com/midnightntwrk/example-bboard/blob/main/api/src/index.ts"
    click A2 "https://github.com/midnightntwrk/example-bboard/blob/main/api/src/common-types.ts"
    click A2 "https://github.com/midnightntwrk/example-bboard/blob/main/api/src/utils/index.ts"
    click A1 "https://github.com/midnightntwrk/example-bboard/blob/main/api/standalone.yml"
    click A1 "https://github.com/midnightntwrk/example-bboard/blob/main/api/tsconfig.json"
    click A1 "https://github.com/midnightntwrk/example-bboard/blob/main/api/tsconfig.build.json"

    %% Click Events for CLI Client
    click CLI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/index.ts"
    click CLI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/launcher/standalone.ts"
    click CLI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/launcher/testnet-local.ts"
    click CLI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/launcher/testnet-remote.ts"
    click CLI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/launcher/testnet-remote-start-proof-server.ts"
    click CLI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/proof-server.yml"
    click CLI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/proof-server-testnet.yml"
    click CLI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/standalone.yml"
    click CLI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/config.ts"
    click CLI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/src/logger-utils.ts"
    click CLI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/tsconfig.json"
    click CLI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/tsconfig.build.json"
    click CLI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/vitest.config.js"
    click CLI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-cli/vitest.setup.js"

    %% Click Events for Web UI
    click UI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/index.html"
    click UI1 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/main.tsx"
    click UI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/components/Board.tsx"
    click UI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/components/Board.EmptyCardContent.tsx"
    click UI2 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/components/TextPromptDialog.tsx"
    click UI2 "https://github.com/midnightntwrk/example-bboard/tree/main/bboard-ui/src/components/Layout"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/contexts/DeployedBoardContext.tsx"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/contexts/BrowserDeployedBoardManager.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/hooks/useDeployedBoardContext.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/contexts/index.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/hooks/index.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/config/theme.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/src/globals.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/vite.config.ts"
    click UI3 "https://github.com/midnightntwrk/example-bboard/blob/main/bboard-ui/.env.testnet"

    %% Click Events for Monorepo & Toolchain
    click Monorepo "https://github.com/midnightntwrk/example-bboard/blob/main/tsconfig.json"
    click Monorepo "https://github.com/midnightntwrk/example-bboard/blob/main/.github/workflows/ci.yaml"
    click Monorepo "https://github.com/midnightntwrk/example-bboard/blob/main/.github/workflows/checkmarx.yaml"

    %% Styles
    classDef package fill:#D0E8FF,stroke:#0055AA,color:#003366
    classDef service fill:#DFFFD0,stroke:#55AA00,color:#336600
    classDef onchain fill:#FFF8D0,stroke:#AAA500,color:#666100
    classDef client fill:#E8FFF4,stroke:#00AA55,color:#006633
```
