# prasannaverse13/devmomentum architecture

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

- Interactive diagram: https://gitdiagram.com/prasannaverse13/devmomentum
- Repository: https://github.com/prasannaverse13/devmomentum

## Overview

##### Project type and purpose
- This is a full-stack Web3 application (“DevCommit Valuator”) that aggregates on-chain oracle data (FTSO price feeds, FDC attestation) with off-chain GitHub metrics to compute a “momentum score” for open-source projects.
- It consists of a React/TypeScript frontend, an Express.js backend (in-memory store), and integrations with external services (Flare Network oracles, GitHub API, MetaMask/Turnkey wallets).

##### File structure
- **Top-level**
– package.json, tsconfig.json, vite.config.ts, drizzle.config.ts (project configs)
– client/ (React frontend)
– server/ (Express backend)
– shared/ (TypeScript schema shared by both client & server)
- **Client folder**
– src/pages (route-driven pages)
– src/components (UI widgets: dashboard cards, FTSO & FDC widgets, wallet/auth components, shadcn/ui library)
– src/contexts & src/hooks (state management, wallet & repository contexts, utilities)
– src/lib (Ethers.js wrappers for FTSO, FDC, GitHub, Turnkey)
- **Server folder**
– index.ts (Express app bootstrap)
– routes.ts (API endpoints: add repo, list metrics, issue attestation)
– storage.ts (in-memory data store)
– vite.ts (server-side build integration)

##### README for technical stack & architecture
- Frontend: React + Vite + TailwindCSS + Chart.js + shadcn/ui
- Backend: Node.js + Express (REST API) + in-memory store (extensible to real DB)
- Blockchain: Ethers.js calls to Flare Coston2 contracts for FTSO & FDC
- Wallets: MetaMask & Turnkey embedded via turnkey.ts + wallet context

a. Main components
- **Client (Browser)**
- UI Layer: React pages & shadcn/ui components
- Business Logic: hooks, contexts, client/src/lib for interacting with oracles & GitHub
- Wallet Layer: MetaMask & Turnkey provider
- **API Server**
- Express.js REST endpoints (server/routes.ts)
- In-memory storage (server/storage.ts)
- Shared type definitions (shared/schema.ts)
- **External Services**
- GitHub API (repository metrics)
- Flare Network (FTSO & FDC smart contracts on Coston2)
- MetaMask / Turnkey (user wallet providers)
b. Relationships & interactions
- Browser → API Server: REST calls to manage tracked repositories and fetch computed scores
- Browser → Flare Oracles: Direct Ethers.js calls (via src/lib/ftso.ts and src/lib/fdc.ts) to fetch real-time data & attestations
- Browser ←→ Wallet: JSON-RPC calls for signing transactions (FTSO attestation, FDC attestation triggers)
- Server → GitHub API: Fetch off-chain metrics if backend augmentation is needed
- Server → Flare Network (optional): Backend-side attestation or data verification
c. Architectural patterns & principles
- **Separation of Concerns**: UI, business logic, data layer, blockchain interactions all in their own modules/directories
- **Context API**: Centralized state for wallet & repository contexts in the client
- **Library/Connector Layer**: src/lib wraps all Ethers.js and HTTP logic for external services
- **Shared Schema**: Type safety across client & server via shared/schema.ts
- **Micro-service-like**: Although a monolith, clear boundaries exist between frontend, backend, and external services
d. Key technologies & libraries
- Frontend: React, TypeScript, Vite, TailwindCSS, shadcn/ui, Chart.js
- Backend: Node.js, Express, Drizzle (for potential DB integration), vite-plugin for server
- Blockchain: Ethers.js, Flare Coston2 contracts (FTSO & FDC)
- Wallets: MetaMask, Turnkey Embedded Wallet

##### Detail without over-complicating
- Shared/schema.ts as a contract between client & server
- Major flows (momentum score calculation, attestation flow) with percent weights or step numbers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser (Client)"
        direction TB
        MainBootstrap["Main Application Bootstrap"]:::frontend
        AppComponent["App Component"]:::frontend
        subgraph "Pages (UI Routes)"
            direction TB
            AddRepoPage["Add Repository Page"]:::frontend
            DashboardPage["Dashboard Page"]:::frontend
            FDCAttPage["FDC Attestations Page"]:::frontend
            FTSOPage["FTSO Feeds Page"]:::frontend
            HowItWorksPage["How It Works Page"]:::frontend
            RepoDetailsPage["Repository Details Page"]:::frontend
            NotFoundPage["404 Page"]:::frontend
        end
        subgraph "Dashboard UI Components"
            direction TB
            CommitCard["Commit Activity Card"]:::frontend
            ContributorsCard["Contributors Card"]:::frontend
            MomentumCard["Momentum Score Card"]:::frontend
            RepoCard["Repository Card"]:::frontend
            TokenPriceCard["Token Price Card"]:::frontend
        end
        subgraph "Oracle & Attestation Widgets"
            direction TB
            FTSOWidget["FTSO Price Feed Widget"]:::frontend
            FDCAttWidget["FDC Attestation Widget"]:::frontend
        end
        subgraph "Wallet & Auth Components"
            direction TB
            TurnkeyAuth["Turnkey Authentication"]:::frontend
            TurnkeyProvider["Turnkey Provider"]:::frontend
            WalletConnect["MetaMask / Wallet Connect"]:::frontend
            WalletGuard["Wallet Guard"]:::frontend
        end
        subgraph "Layout Components"
            direction TB
            MainLayout["Main Content Layout"]:::frontend
            SidebarLayout["Sidebar Layout"]:::frontend
        end
        subgraph "State & Context"
            direction TB
            RepoContext["Repository Context"]:::frontend
            WalletContext["Wallet Context"]:::frontend
        end
        subgraph "Hooks & Utilities"
            direction TB
            MobileHook["Mobile Detection Hook"]:::frontend
            ToastHook["Toast Hook"]:::frontend
            Utils["Utility Functions"]:::frontend
        end
        subgraph "External Connectors (src/lib)"
            direction TB
            FTSOConnector["FTSO Connector"]:::frontend
            FDCConnector["FDC Connector"]:::frontend
            GitHubConnector["GitHub API Connector"]:::frontend
            TurnkeyConnector["Turnkey Wallet Connector"]:::frontend
            QueryClient["React Query Client"]:::frontend
        end
    end

    %% Shared Schema
    SharedSchema["Shared Schema (shared/schema.ts)"]:::shared

    %% Backend Layer
    subgraph "API Server (Express.js)"
        direction TB
        ServerBootstrap["Server Bootstrap (index.ts)"]:::backend
        APIRoutes["API Routes (routes.ts)"]:::backend
        Storage["In-Memory Storage"]:::db
        ViteServer["Server Build Integration (vite.ts)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHubAPI["GitHub API"]:::external
        FlareOracles["Flare Coston2 Oracles"]:::external
        WalletProviders["MetaMask / Turnkey Providers"]:::external
    end

    %% Connections
    MainBootstrap --> AppComponent
    AppComponent --> AddRepoPage
    AppComponent --> DashboardPage
    AppComponent --> FDCAttPage
    AppComponent --> FTSOPage
    AppComponent --> HowItWorksPage
    AppComponent --> RepoDetailsPage
    AppComponent --> NotFoundPage

    DashboardPage --> CommitCard
    DashboardPage --> ContributorsCard
    DashboardPage --> MomentumCard
    DashboardPage --> RepoCard
    DashboardPage --> TokenPriceCard

    AddRepoPage --> MainLayout
    DashboardPage --> MainLayout
    FDCAttPage --> MainLayout
    FTSOPage --> MainLayout
    HowItWorksPage --> MainLayout
    RepoDetailsPage --> MainLayout
    NotFoundPage --> MainLayout

    MainLayout --> SidebarLayout

    AppComponent --> RepoContext
    AppComponent --> WalletContext

    RD["UI Calls"]:::flow --> APIRoutes
    DashboardPage -->|"REST"| APIRoutes
    AddRepoPage -->|"REST"| APIRoutes
    FDCAttPage -->|"REST"| APIRoutes
    FTSOPage -->|"REST"| APIRoutes
    RepoDetailsPage -->|"REST"| APIRoutes

    FDCAttWidget --> FDCConnector
    FTSOWidget --> FTSOConnector

    FDCConnector --> FlareOracles
    FTSOConnector --> FlareOracles

    GitHubConnector --> GitHubAPI

    WalletConnect --> WalletProviders
    TurnkeyAuth --> WalletProviders
    TurnkeyProvider --> WalletProviders

    RepoContext --> QueryClient
    WalletContext --> TurnkeyConnector

    Utils --> FTSOConnector
    Utils --> FDCConnector
    Utils --> GitHubConnector

    APIRoutes --> Storage
    ServerBootstrap --> APIRoutes
    ServerBootstrap --> ViteServer
    APIRoutes --> SharedSchema
    AppComponent --> SharedSchema

    APIRoutes --> GitHubAPI
    APIRoutes --> FlareOracles

    %% Click Events
    click MainBootstrap "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/main.tsx"
    click AppComponent "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/App.tsx"
    click AddRepoPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/add-repository.tsx"
    click DashboardPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/dashboard.tsx"
    click FDCAttPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/fdc-attestations.tsx"
    click FTSOPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/ftso-feeds.tsx"
    click HowItWorksPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/how-it-works.tsx"
    click RepoDetailsPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/repository-details.tsx"
    click NotFoundPage "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/pages/not-found.tsx"
    click CommitCard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/dashboard/commit-activity-card.tsx"
    click ContributorsCard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/dashboard/contributors-card.tsx"
    click MomentumCard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/dashboard/momentum-score-card.tsx"
    click RepoCard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/dashboard/repository-card.tsx"
    click TokenPriceCard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/dashboard/token-price-card.tsx"
    click FTSOWidget "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/ftso/price-feed-widget.tsx"
    click FDCAttWidget "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/fdc/attestation-widget.tsx"
    click TurnkeyAuth "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/turnkey/turnkey-auth.tsx"
    click TurnkeyProvider "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/turnkey/turnkey-provider.tsx"
    click WalletConnect "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/wallet/wallet-connect.tsx"
    click WalletGuard "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/auth/wallet-guard.tsx"
    click MainLayout "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/layout/main-content.tsx"
    click SidebarLayout "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/components/layout/sidebar.tsx"
    click RepoContext "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/contexts/repository-context.tsx"
    click WalletContext "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/contexts/wallet-context.tsx"
    click MobileHook "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/hooks/use-mobile.tsx"
    click ToastHook "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/hooks/use-toast.ts"
    click Utils "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/utils.ts"
    click FTSOConnector "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/ftso.ts"
    click FDCConnector "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/fdc.ts"
    click GitHubConnector "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/github.ts"
    click TurnkeyConnector "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/turnkey.ts"
    click QueryClient "https://github.com/prasannaverse13/devmomentum/blob/main/client/src/lib/queryClient.ts"
    click ServerBootstrap "https://github.com/prasannaverse13/devmomentum/blob/main/server/index.ts"
    click APIRoutes "https://github.com/prasannaverse13/devmomentum/blob/main/server/routes.ts"
    click Storage "https://github.com/prasannaverse13/devmomentum/blob/main/server/storage.ts"
    click ViteServer "https://github.com/prasannaverse13/devmomentum/blob/main/server/vite.ts"
    click SharedSchema "https://github.com/prasannaverse13/devmomentum/blob/main/shared/schema.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#28a745,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#fb8c00,stroke-width:1px
    classDef db fill:#FFF2B2,stroke:#c07e00,stroke-width:1px
    classDef shared fill:#E8E8E8,stroke:#888888,stroke-width:1px
    classDef flow stroke-dasharray: 5 5,stroke:#666
```
