# afk-alignedfamkernel/afk_monorepo architecture

> Architecture diagram of the GitHub repository afk-alignedfamkernel/afk_monorepo, 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/afk-alignedfamkernel/afk_monorepo
- Repository: https://github.com/afk-alignedfamkernel/afk_monorepo

## Overview

This monorepo project is a decentralized social network that uniquely integrates Nostr (a censorship-resistant social protocol) with Starknet account abstraction via smart contracts (written in Cairo and even Solidity in some parts) to build a social layer where users can tip and interact using either the “WalletConnect” or “SocialPay” mechanisms. The overall purpose is to build a decentralized social network (“AFK Community”) that aligns web3 users and their identities, letting them interact, send tips, and participate in social actions through both on-chain and off-chain systems.

##### Main Components
- Frontend Applications:
- Mobile App (located in apps/mobile) built with React Native & Expo.
- Website / PWA (located in apps/website, apps/pwa) built likely with Next.js.
- Backend Services:
- Data backend (apps/data-backend) written in (likely) Node/TypeScript.
- Several backend implementations including pixel-backend and Go-based backend (found under “backend”).
- Indexers & Relayers:
- Several indexer components (e.g., apps/indexer, apps/nestjs-indexer) that collect blockchain events.
- Onchain / Smart Contracts:
- Onchain folder contains Starknet smart contracts in Cairo, as well as Solidity contracts.
- Separate contract components for account abstraction and token/tip deposit contracts.
- Packages / SDKs:
- Common utilities and SDKs (packages/common, packages/afk_nostr_sdk, packages/afk_react_sdk, etc.) to allow integration with the Nostr protocol and blockchain.
- Scripts & Tools:
- A variety of scripts for deployment and testing of Cairo code, along with Turborepo config (turbo.json) to orchestrate the monorepo.

##### Relationships and Interactions
- Users interact via either the Mobile App or Website. Both frontends communicate with backend services via REST APIs or GraphQL.
- The backend services handle social actions such as posting, sending tips, and interacting with user profiles. They also interface with the blockchain:
- For tip flows: a user (e.g., “Alice”) approves a token transfer to a Deposit/Transfer smart contract and then submits a deposit/claim transaction via the backend.
- Indexers continuously pull and process blockchain events (using Apibara or NestJS indexers) to update the social data or trigger notifications.
- The onchain layer (the smart contracts) is the ultimate source of truth regarding tip deposits, account abstraction, and token transfers – these receive instructions from both the backend and indexers.
- The SDK packages support communication between frontend apps and the blockchain or Nostr servers, abstracting protocol details.

##### Architectural Patterns and Technologies
- The system uses a monorepo structure (managed by Turborepo) where apps and packages are separated but interconnected.
- Microservice and layered architectures are in play: frontends opt for separation of concerns (mobile vs. web), backends are split into specialized services (data backend, pixel-backend, indexers), and onchain smart contracts form an independent trust layer.
- Key technologies include React Native/Expo (mobile), Next.js (website), Go and NestJS for backend services, TypeScript for the Nostr relayer and SDKs, and Cairo (plus supporting tools like Scarb and SnForge) for smart contracts on Starknet.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontends"
        FMobile["Mobile App (React Native & Expo)"]:::frontend
        FWebsite["Website (Next.js)"]:::frontend
        FPWA["PWA (Next.js)"]:::frontend
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        BData["Data Backend (Node/TypeScript)"]:::backend
        BPixel["Pixel Backend (Go)"]:::backend
        BOther["Other Backend Implementations"]:::backend
    end

    %% Indexers & Relayers Layer
    subgraph "Indexers & Relayers"
        IStandard["Standard Indexer"]:::indexer
        INestJS["NestJS Indexer"]:::indexer
        INestJS2["NestJS Indexer (v2)"]:::indexer
    end

    %% Onchain Smart Contracts Layer
    subgraph "Onchain Smart Contracts"
        OStarknet["Starknet Contracts (Cairo)"]:::onchain
        OSolidity["Solidity Contracts"]:::onchain
    end

    %% Packages / SDKs Layer
    subgraph "Packages / SDKs"
        NostrSDK["AFK Nostr SDK"]:::sdk
        ReactSDK["AFK React SDK"]:::sdk
        AFKSDK["AFK SDK"]:::sdk
        CommonSDK["Common Utilities"]:::sdk
    end

    %% Scripts & Deployment Tools Layer
    subgraph "Scripts & Deployment Tools"
        SDeploy["Deployment & Testing Scripts"]:::scripts
        STurbo["Turborepo Configuration"]:::scripts
    end

    %% Relationships among components
    %% Frontends interact with Backend Services
    FMobile -->|"interacts"| BData
    FWebsite -->|"interacts"| BData
    FPWA -->|"interacts"| BData

    FMobile -->|"also interacts"| BOther
    FWebsite -->|"also interacts"| BOther
    FPWA -->|"also interacts"| BOther

    %% Backend Services initiate onchain transactions
    BData -->|"tx-initiation"| OStarknet
    BPixel -->|"tx-initiation"| OStarknet
    BOther -->|"tx-initiation"| OStarknet

    %% Indexers provide blockchain event updates to Backend Services
    IStandard -->|"event-update"| BData
    INestJS -->|"event-update"| BData
    INestJS2 -->|"event-update"| BData

    %% SDKs integrate with both Frontend and Backend
    NostrSDK ---|"integration"| FMobile
    NostrSDK ---|"integration"| FWebsite
    NostrSDK ---|"integration"| FPWA
    NostrSDK ---|"integration"| BData
    NostrSDK ---|"integration"| BPixel
    NostrSDK ---|"integration"| BOther

    ReactSDK ---|"integration"| FMobile
    ReactSDK ---|"integration"| FWebsite
    ReactSDK ---|"integration"| FPWA
    ReactSDK ---|"integration"| BData

    AFKSDK ---|"integration"| BData
    CommonSDK ---|"integration"| FMobile
    CommonSDK ---|"integration"| FWebsite
    CommonSDK ---|"integration"| FPWA
    CommonSDK ---|"integration"| BData

    %% Onchain components relation
    OStarknet ---|"sourceOfTruth"| OSolidity

    %% Tip Flow Scenarios inset (Mini-sequence)
    subgraph "Tip Flow Scenarios"
        direction LR
        TC1["WalletConnect: Escrow"]:::tip
        TC2["WalletConnect: Claim"]:::tip
        SP["SocialPay: DirectTransfer"]:::tip
        TC1 --> TC2
    end

    %% Backend triggers tip flows
    BData ---|"triggers"| TC1
    BData ---|"triggers"| SP

    %% Click Event assignments
    click FMobile "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/mobile"
    click FWebsite "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/website"
    click FPWA "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/pwa"
    click BData "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/data-backend"
    click BPixel "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/pixel-backend"
    click BOther "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/backend"
    click IStandard "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/indexer"
    click INestJS "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/nestjs-indexer"
    click INestJS2 "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/apps/indexer-v2"
    click OStarknet "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/onchain/cairo"
    click OSolidity "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/onchain/solidity_contracts"
    click NostrSDK "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/packages/afk_nostr_sdk"
    click ReactSDK "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/packages/afk_react_sdk"
    click AFKSDK "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/packages/afk_sdk"
    click CommonSDK "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/packages/common"
    click STurbo "https://github.com/afk-alignedfamkernel/afk_monorepo/blob/main/turbo.json"
    click SDeploy "https://github.com/afk-alignedfamkernel/afk_monorepo/tree/main/scripts"

    %% Style definitions for color coding
    classDef frontend fill:#a3d5ff,stroke:#000,stroke-width:2px;
    classDef backend fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef indexer fill:#d1ffd1,stroke:#000,stroke-width:2px;
    classDef onchain fill:#fef9c3,stroke:#000,stroke-width:2px;
    classDef sdk fill:#e0bbff,stroke:#000,stroke-width:2px;
    classDef scripts fill:#ffe4b5,stroke:#000,stroke-width:2px;
    classDef tip fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
