# neynarxyz/farcaster-examples architecture

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

- Interactive diagram: https://gitdiagram.com/neynarxyz/farcaster-examples
- Repository: https://github.com/neynarxyz/farcaster-examples

## Overview

##### Project type and purpose
- This is a monorepo called farcaster-examples containing a collection of small Farcaster-powered mini-apps and utilities, each demonstrating different integrations with the Neynar SDK and Farcaster network (e.g. scripts, bots, Next.js/React front-ends, a Flask service, a Kafka consumer, and a React Native app).

##### File structure
- Top-level folders each represent an independent component:
- archiver-script (Node.js CLI)
- cast-action (Node.js SDK demo)
- fc2x (Next.js cross-poster frontend + API)
- flask-app (Python Flask microservice)
- frames-bot & gm-bot (TypeScript bots)
- managed-signers (Next.js app with API routes)
- neynar-webhook-kafka-consumer (Node.js Kafka consumer)
- wownar-react-native (Expo mobile client + small Node server)
- wownar-react-sdk & wownar (Next.js demo front-ends)
- Notice repeated patterns: Next.js “src/app” directory with file-based API routes, standalone package.json per subfolder, TypeScript/JavaScript mix, .env examples, frameworks (Tailwind, React, Flask), build configs (tsconfig, bun.lockb).

##### Extract architectural insights from README
- Each mini-app shows a different use case of Neynar/Farcaster: archiving, cross-posting, bots, managed signers, SIWN integration. No single unified backend; instead a suite of loosely related services.

##### Main components
a. Repository root (monorepo container)
b. Sub-projects grouped by category:
- Scripts & Bots
- archiver-script
- cast-action
- frames-bot
- gm-bot
- neynar-webhook-kafka-consumer
- Front-end Apps (Next.js/React)
- fc2x
- managed-signers
- wownar-react-sdk
- wownar
- Mobile Client
- wownar-react-native (Expo) + small Node server
- Microservice
- flask-app
c. External systems: Farcaster network (via Neynar), Warpcast API, Kafka cluster, EVM channel

##### Relationships and data flows
- All sub-projects import the Neynar client library to authenticate and call the Farcaster API.
- Next.js apps expose UI to end users and file-based API routes under `/api/*` that call Neynar client or access a database (if any).
- Scripts and bots run standalone Node processes (cron or event-driven), using Neynar SDK to post or fetch casts.
- The Kafka consumer listens on a topic, processes webhook events, and forwards to Neynar or external services.
- The Flask service polls or receives EVM channel events, processes casts, and may store or forward data.
- The Expo mobile app calls its bundled Node server or directly uses the Neynar SDK via HTTP endpoints.

##### Architectural patterns & principles
- Monorepo containerization: iterate and share common dependencies (e.g. Neynar client).
- Micro-frontend/microservice style: each feature lives in its own project folder.
- Next.js file-based routing for front-end + lightweight API backend in same codebase.
- Decoupled bots and consumers as event-driven services.
- SIWN (Sign-In with Ethereum) flows embedded in Next.js & React Native apps.

##### Essential elements
- Arrowheads indicating call direction and trigger types
- Annotation of key design patterns (e.g. “File-based API Routes,” “Event-Driven Bot”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Services"
        direction TB
        FarcasterCloud(("Farcaster Network / Warpcast API")):::cloud
        KafkaBroker[(Kafka Broker)]:::db
        EVMChannel[(Ethereum/EVM Channel)]:::db
    end

    %% Monorepo Container
    subgraph "Monorepo: farcaster-examples" 
        direction TB

        %% Shared Library
        NeynarLib["Neynar Client Library"]:::lib

        %% Scripts & Bots Cluster
        subgraph "Scripts & Bots" 
            direction TB
            Archiver["archiver-script\n(Node.js CLI)"]:::script
            CastAction["cast-action\n(Node.js SDK Demo)"]:::script
            FramesBot["frames-bot\n(TypeScript Bot)"]:::script
            GMBot["gm-bot\n(TypeScript/EVM Signer Bot)"]:::script
        end

        %% Kafka Consumer Cluster
        subgraph "Kafka Consumer" 
            direction TB
            KafkaConsumer["neynar-webhook-kafka-consumer\n(Node.js Kafka Consumer)"]:::consumer
        end

        %% Frontend Apps Cluster
        subgraph "Next.js Frontends + APIs" 
            direction TB
            FC2X["fc2x\n(Next.js Cross-Poster)"]:::frontend
            ManagedSigners["managed-signers\n(Next.js App)"]:::frontend
            WownarSDK["wownar-react-sdk\n(Next.js Demo)"]:::frontend
            Wownar["wownar\n(Next.js Demo)"]:::frontend
        end

        %% Mobile Cluster
        subgraph "Mobile Client + Server" 
            direction TB
            MobileClient["wownar-react-native/client\n(Expo React Native)"]:::mobile
            MobileServer["wownar-react-native/server\n(Node.js Server)"]:::server
        end

        %% Microservice Cluster
        subgraph "Flask Microservice" 
            direction TB
            FlaskApp["flask-app\n(Python Flask)"]:::micro
        end
    end

    %% Relationships: Shared Library usage
    Archiver -->|imports SDK RPC| NeynarLib
    CastAction -->|imports SDK RPC| NeynarLib
    FramesBot -->|imports SDK RPC| NeynarLib
    GMBot -->|imports SDK RPC| NeynarLib
    FC2X -->|calls API routes| NeynarLib
    ManagedSigners -->|calls API routes| NeynarLib
    WownarSDK -->|calls API routes| NeynarLib
    Wownar -->|calls API routes| NeynarLib
    KafkaConsumer -->|imports SDK RPC| NeynarLib
    MobileClient -->|uses SDK via HTTP| MobileServer
    MobileServer -->|imports SDK RPC| NeynarLib
    FlaskApp -->|imports SDK RPC| NeynarLib

    %% Relationships: Monorepo to external
    NeynarLib -->|SDK RPC| FarcasterCloud
    KafkaConsumer -->|subscribes| KafkaBroker
    FlaskApp -->|HTTP REST| EVMChannel

    %% Click Events
    click Archiver "https://github.com/neynarxyz/farcaster-examples/tree/main//archiver-script"
    click CastAction "https://github.com/neynarxyz/farcaster-examples/blob/main//cast-action/src/index.tsx"
    click FramesBot "https://github.com/neynarxyz/farcaster-examples/blob/main//frames-bot/index.ts"
    click GMBot "https://github.com/neynarxyz/farcaster-examples/blob/main//gm-bot/src/app.ts"
    click KafkaConsumer "https://github.com/neynarxyz/farcaster-examples/blob/main//neynar-webhook-kafka-consumer/src/index.ts"
    click FC2X "https://github.com/neynarxyz/farcaster-examples/tree/main//fc2x/src/app"
    click ManagedSigners "https://github.com/neynarxyz/farcaster-examples/tree/main//managed-signers/src/app/api"
    click WownarSDK "https://github.com/neynarxyz/farcaster-examples/tree/main//wownar-react-sdk/src/app"
    click Wownar "https://github.com/neynarxyz/farcaster-examples/tree/main//wownar/src/app"
    click MobileClient "https://github.com/neynarxyz/farcaster-examples/blob/main//wownar-react-native/client/App.tsx"
    click MobileServer "https://github.com/neynarxyz/farcaster-examples/blob/main//wownar-react-native/server/index.js"
    click FlaskApp "https://github.com/neynarxyz/farcaster-examples/blob/main//flask-app/app.py"

    %% Styles
    classDef cloud fill:#A0E0FF,stroke:#333,stroke-width:1px
    classDef db fill:#FFCCCC,stroke:#333,stroke-width:1px
    classDef lib fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef script fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef consumer fill:#FFCCCC,stroke:#333,stroke-width:1px
    classDef frontend fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef mobile fill:#FFD580,stroke:#333,stroke-width:1px
    classDef server fill:#FFB347,stroke:#333,stroke-width:1px
    classDef micro fill:#E0CCFF,stroke:#333,stroke-width:1px
```
