# byhow/matters-forum architecture

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

- Interactive diagram: https://gitdiagram.com/byhow/matters-forum
- Repository: https://github.com/byhow/matters-forum

## Overview

##### Main Components
- Frontend UI – Built with Next.js (using the App Router), incorporating pages for the feed, individual items (with comment and reply components), search, and RSS views.
- API Endpoints – Located under src/app/api, which includes subdirectories for IPFS, RSS, and webhook interactions.
- Cron Jobs – A specialized route in src/app/cron that periodically catches missed events.
- Blockchain and Wallet Connect – Integration using RainbowKit, Wagmi, and viem.sh for onchain interactions (e.g., curation events on Optimism).
- Database Layer – Managed via Drizzle ORM for Postgres (with the schema defining curations, comments, and users) hosted on Supabase.
- Other Libraries & Tools:
○ IPFS gateway integration for content fetching.
○ Rate limiting functionality implemented using Vercel KV/Redis.
○ Utility functions and hooks in src/lib to support business logic.

##### Interaction & Data Flow
- User Access:
- The user lands on a feed page (hackernews-esque interface), which fetches posts from the database.
- Navigation between sorting pages (/newest, /trend, /priciest) defines how data is retrieved, ordered, and presented.
- Post and Comment Interaction:
- Selecting a post leads to an individual item page that retrieves content from IPFS (via the unstable public gateway or a paid plan) and displays comments.
- Comment functionality requires wallet connect; the blockchain integration is kickstarted using RainbowKit/Wagmi.
- API Operations:
- API routes under src/app/api manage operations for IPFS data retrieval, RSS feed generation, and webhook processing.
- A cron endpoint is scheduled to fill any gaps missed by the event listener on Optimism (using viem.watchEvent) and update the database.
- Database & ORM:
- Drizzle ORM communicates with the Postgres database (schema found in src/lib/db/schema.ts) to persist curations, comments, and user data.
- Supporting Utilities:
- Hooks (e.g., useIsMounted) and libs (e.g., rate-limit, subscribe) play auxiliary roles in ensuring a smooth client and server experience with type safety (using Zod).

##### Architectural Patterns and Relationships
- Separation of Concerns:
- The client-facing interface is clearly separated from API logic; the Next.js app directory clearly splits server-side and client-side components.
- Event-Driven Updates:
- The integration with viem.sh to listen for onchain events and a complementary cron job demonstrate an event-driven design to update the database.
- Decentralized Interactions:
- The system leverages decentralized data (via IPFS) and blockchain wallet authentication, creating an interface that is both modern and decentralized.
- RESTful & SSG/SSR Renders:
- The API endpoints alongside the server-side rendering of different pages (feed, item, RSS) exhibit a mix of SSR and API-based interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U["User"]:::user

    %% Frontend Subgraph
    subgraph "Frontend (Next.js)"
        F["Feed Page"]:::frontend
        I["Item Page"]:::frontend
        S["Search Page"]:::frontend
        SI["Search Input"]:::frontend
        R["RSS Page"]:::frontend
    end

    %% Backend/API Subgraph
    subgraph "Backend/API"
        IPFSAPI["IPFS API Endpoint"]:::backend
        RSSAPI["RSS API Endpoint"]:::backend
        WEBHOOKAPI["Webhook API Endpoint"]:::backend
        CRONJOB["Cron Job"]:::backend
    end

    %% Blockchain/Web3 Subgraph
    subgraph "Blockchain/Web3"
        WALLET["Wallet Connect"]:::blockchain
        ONCHAIN["Onchain Listener"]:::blockchain
    end

    %% External Services Subgraph
    subgraph "External Services"
        IPFSGW["IPFS Gateway"]:::external
        RATEEXT["Rate Limiter (Vercel KV/Redis)"]:::external
        OPTIMISM["Optimism (Blockchain)"]:::external
    end

    %% Database Subgraph
    subgraph "Database (Supabase Postgres)"
        DB_ACCESS["DB Access (Drizzle ORM)"]:::database
        DB_SCHEMA["DB Schema (Drizzle ORM)"]:::database
        DB_ACCESS --- DB_SCHEMA
    end

    %% Utilities & Hooks Subgraph
    subgraph "Utilities & Hooks"
        ISMOUNT["useIsMounted Hook"]:::utility
        RATELIMIT["Rate Limit Utility"]:::utility
        IPFSUTIL["IPFS Utility"]:::utility
        SUBSCRIBE["Subscribe Utility"]:::utility
        GENUTILS["General Utils"]:::utility
    end

    %% Data Flow Arrows
    U -->|"accesses"| F
    U -->|"accesses"| I
    U -->|"accesses"| S
    U -->|"accesses"| SI
    U -->|"accesses"| R

    %% Frontend to Backend/API
    F -->|"fetchPosts"| DB_ACCESS
    I -->|"fetchComments"| DB_ACCESS
    I -->|"fetchIPFSContent"| IPFSAPI
    R -->|"generateRSS"| RSSAPI

    %% API Endpoints to External/Database
    IPFSAPI -->|"retrieveContent"| IPFSGW
    WEBHOOKAPI -->|"processEvent"| DB_ACCESS
    CRONJOB -->|"updateDB"| DB_ACCESS

    %% Blockchain Integration
    I -->|"initiateWallet"| WALLET
    WALLET -->|"triggers"| ONCHAIN
    ONCHAIN -->|"listensOn"| OPTIMISM
    ONCHAIN -->|"updateDB"| DB_ACCESS

    %% Utilities support Frontend and API
    F ---|"supports"| ISMOUNT
    I --- RATELIMIT
    S --- IPFSUTIL
    SI --- SUBSCRIBE
    R --- GENUTILS

    %% Styles
    classDef user fill:#FFEEAA,stroke:#333,stroke-width:2px;
    classDef frontend fill:#D1E8FF,stroke:#333,stroke-width:2px;
    classDef backend fill:#F9D6AC,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#FFD1DC,stroke:#333,stroke-width:2px;
    classDef external fill:#EAEAEA,stroke:#333,stroke-width:2px;
    classDef database fill:#E6FFE6,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFF2CC,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend
    click F "https://github.com/byhow/matters-forum/blob/main/src/app/(feed)/page.tsx"
    click I "https://github.com/byhow/matters-forum/blob/main/src/app/(feed)/item/[id]/page.tsx"
    click S "https://github.com/byhow/matters-forum/blob/main/src/app/(feed)/search/page.tsx"
    click SI "https://github.com/byhow/matters-forum/blob/main/src/app/(feed)/search/input.tsx"
    click R "https://github.com/byhow/matters-forum/blob/main/src/app/(feed)/rss/page.tsx"

    %% Click Events for API Endpoints
    click IPFSAPI "https://github.com/byhow/matters-forum/blob/main/src/app/api/ipfs/route.ts"
    click RSSAPI "https://github.com/byhow/matters-forum/blob/main/src/app/api/rss/route.ts"
    click WEBHOOKAPI "https://github.com/byhow/matters-forum/blob/main/src/app/api/webhook/route.ts"
    click CRONJOB "https://github.com/byhow/matters-forum/blob/main/src/app/cron/route.ts"

    %% Click Events for Blockchain/Web3
    click WALLET "https://github.com/byhow/matters-forum/blob/main/src/components/rainbow-button.tsx"
    click ONCHAIN "https://github.com/byhow/matters-forum/blob/main/src/lib/optimism.ts"

    %% Click Events for Database
    click DB_ACCESS "https://github.com/byhow/matters-forum/blob/main/src/lib/db/index.ts"
    click DB_SCHEMA "https://github.com/byhow/matters-forum/blob/main/src/lib/db/schema.ts"

    %% Click Events for Utilities & Hooks
    click ISMOUNT "https://github.com/byhow/matters-forum/blob/main/src/lib/hooks/useIsMounted.ts"
    click RATELIMIT "https://github.com/byhow/matters-forum/blob/main/src/lib/rate-limit.ts"
    click IPFSUTIL "https://github.com/byhow/matters-forum/blob/main/src/lib/ipfs.ts"
    click SUBSCRIBE "https://github.com/byhow/matters-forum/blob/main/src/lib/subscribe.ts"
    click GENUTILS "https://github.com/byhow/matters-forum/blob/main/src/lib/utils.ts"
```
