# sanidhyarathore/teamverse-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/sanidhyarathore/teamverse-frontend
- Repository: https://github.com/sanidhyarathore/teamverse-frontend

## Overview

##### Project type and purpose
- Teamverse-Frontend is a standalone web application built on Next.js (App Router) that provides a gamified, blockchain-enabled team-bonding experience.
- It’s primarily a front-end SPA/SSR hybrid that:
- Renders game pages and onboarding flows under `/app`
- Hosts reusable UI components in `components`, `components/ui`, and `app/components`
- Integrates with Argent Invisible Wallet for seamless Web3 authentication and transaction submission

##### File structure
Top-level areas:
- `/app` – Next.js App Router: page folders (e.g. `create`, `game-setup`, `leaderboard`, etc.), global layout and CSS
- `/components` – shared, cross-page React components, contexts, hooks under `/hooks`
- `/lib` & `/app/lib` – utility functions and constants
- Config & metadata – `next.config.ts`, Tailwind/PostCSS configs, ESLint, TypeScript

Architectural patterns & clues:
- File-based routing via nested `/app` directories → each folder with `page.tsx` is a route
- Presentation layer separated into UI primitives (`components/ui` and `app/components`) and higher-level page components
- State management via React Context (`DarkModeContext`), custom hooks (`useToast`), and local store in onboarding
- External integration points (Argent wallet, potential backend APIs or blockchain RPC endpoints stored in env vars)

##### Key README insights
- Tech stack: Next.js (SSR/SSG), Tailwind CSS, Radix UI, TypeScript, Wallet integration
- Purpose: drive user flows (onboarding → choose game → play → leaderboard)
- Blockchain is used as an inclusion layer via Argent Invisible Wallet

##### Diagramming guidance
a. Main components to represent:
– Browser / Client – React app running in user’s browser
– Next.js Server (if SSR/Edge), rendering pages and handling API routes (if any)
– UI Layer – presentational components and page layouts
– State Layer – React Contexts, custom hooks, local store (Onboarding store)
– Integration Layer – Web3 connector (Argent Invisible Wallet SDK), utility libs, API service modules
– External Services – Blockchain network (e.g. Ethereum L2), optional backend or API endpoints

b. Relationships & interactions:
- User’s browser issues HTTP/SSR requests to Next.js server → server renders or hydrates React pages
- UI components use Contexts/hooks to fetch or mutate data
- Integration layer invokes Argent Wallet SDK for authentication, signing, and on-chain transactions
- Static assets loaded directly from CDN or `public`

c. Architectural patterns & principles:
– Separation of concerns: routing (Next.js App Router) vs. presentation (components) vs. integration (lib/hooks)
– Component re-use: UI primitives (Radix + Tailwind) are wrapped in `components/ui` and used throughout
– Unidirectional data flow: page → layout → components → hooks → services
– Feature folders under `/app` for collocating code for each route

d. Technologies & frameworks to annotate:
- Next.js App Router (SSR/SSG/ISR)
- React + TypeScript
- Tailwind CSS + Radix UI
- Argent Invisible Wallet (Web3 onboarding)
- Custom hooks & Context API
- Node-based build & dev server (Vercel or self-hosted)

##### Detail & coverage
– Call out shared contexts (DarkModeContext, Toast)
– Indicate environment variables driving the integration endpoints
– Show potential build/deploy pipeline (GitHub Actions CI → Vercel) at a high level if relevant

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser
    Browser["User's Browser"]:::external

    %% Next.js Server
    subgraph "Next.js Server (SSR/SSG)" 
        direction TB
        RoutingLayer["Routing Layer (/app)"]:::frontend

        subgraph "Onboarding Flow"
            direction TB
            OnboardingPage["Onboarding Page & Layout"]:::frontend
            OnboardingLayout["OnboardingLayout"]:::frontend
            Progress["Progress Component"]:::frontend
            OnboardingSteps["OnboardingSteps"]:::frontend
            OnboardingButton["Button"]:::frontend
            Glass["Glass"]:::frontend
        end

        subgraph "Create Team"
            direction TB
            CreateTeamPage["Create Team Page"]:::frontend
            CreateTeamComp["CreateTeam Component"]:::frontend
        end

        subgraph "Game Setup"
            GameSetupPage["Game Setup Page"]:::frontend
        end

        subgraph "Play Routes"
            direction TB
            MysteryTeammate["Mystery Teammate Page"]:::frontend
            TwoTruthsLie["Two-Truths-Lie Page"]:::frontend
            VersePlayer["Verse Player Page"]:::frontend
            WeekendActivity["Weekend Activity Page"]:::frontend
        end

        subgraph "Leaderboard"
            direction TB
            LeaderboardPage["Leaderboard Page & Layout"]:::frontend
            GameModeSelector["GameModeSelector"]:::frontend
            LeaderboardHeader["Header Component"]:::frontend
            PlayerCard["PlayerCard"]:::frontend
            AvatarUI["Avatar UI Primitive"]:::frontend
        end

        subgraph "Global Config"
            GlobalLayout["Global Layout"]:::frontend
            GlobalStyles["Global Styles"]:::frontend
            RootPage["Root Page"]:::frontend
        end
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        SharedComponents["Shared Components"]:::frontend
        UIPrimitives["UI Primitives (components/ui)"]:::frontend
    end

    %% State & Integration Layer
    subgraph "State & Integration Layer"
        direction TB
        CustomHooks["Custom Hooks & Contexts"]:::state
        Utils["Utility Libraries"]:::state
        WalletIntegration["Web3 / Wallet Integration"]:::state
    end

    %% External Services & Assets
    subgraph "External Services & Assets"
        direction TB
        StaticAssets["Static Asset Store"]:::external
        BackendAPI["Backend API / GraphQL"]:::external
        Blockchain["Blockchain Network (Ethereum L2)"]:::external
        CI_CD["CI/CD Workflow"]:::external
    end

    %% Connections
    Browser -->|HTTP/HTTPS| RoutingLayer
    RoutingLayer -->|"renders/hydrates"| SharedComponents
    SharedComponents --> UIPrimitives
    SharedComponents --> CustomHooks
    SharedComponents --> WalletIntegration
    CustomHooks --> Utils
    WalletIntegration --> Blockchain
    SharedComponents -->|"REST/GraphQL"| BackendAPI
    Browser -->|"loads assets"| StaticAssets

    %% Click Events - Routing Layer Onboarding
    click OnboardingPage "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/page.tsx"
    click OnboardingLayout "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/OnboardingLayout.tsx"
    click Progress "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/Progress.tsx"
    click OnboardingSteps "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/OnboardingSteps.tsx"
    click OnboardingButton "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/Button.tsx"
    click Glass "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/Glass.tsx"
    click OnboardingStore "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/lib/store.ts"
    click OnboardingConstants "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/lib/constants.ts"
    click OnboardingTypes "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/onboarding/lib/types.ts"

    %% Create Team
    click CreateTeamPage "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/create/page.tsx"
    click CreateTeamComp "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/components/CreateTeam.tsx"

    %% Game Setup
    click GameSetupPage "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/game-setup/page.tsx"

    %% Play Routes
    click MysteryTeammate "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/mystery-teammate/page.tsx"
    click TwoTruthsLie "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/two-truth-lie/page.tsx"
    click VersePlayer "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/verse-player/page.tsx"
    click WeekendActivity "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/weekendActivity/page.tsx"

    %% Weekend Activity subcomponents
    click ActivityFeed "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/weekendActivity/activity-feed.tsx"
    click ChannelTabs "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/weekendActivity/channel-tabs.tsx"
    click ImageUploader "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/weekendActivity/image-uploader.tsx"
    click UploadWeekend "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/weekendActivity/upload-weekend-activity.tsx"

    %% Leaderboard
    click LeaderboardPage "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/page.tsx"
    click LeaderboardLayout "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/components/LeaderboardLayout.tsx"
    click GameModeSelector "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/components/GameModeSelector.tsx"
    click LeaderboardHeader "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/components/Header.tsx"
    click PlayerCard "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/components/PlayerCard.tsx"
    click AvatarUI "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/leaderboard/ui/Avatar.tsx"

    %% Global Config
    click GlobalLayout "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/layout.tsx"
    click GlobalStyles "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/globals.css"
    click RootPage "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/app/page.tsx"

    %% Shared Components & UI Primitives
    click SharedComponents "https://github.com/sanidhyarathore/teamverse-frontend/tree/main/components"
    click UIPrimitives "https://github.com/sanidhyarathore/teamverse-frontend/tree/main/components/ui"

    %% State & Integration
    click CustomHooks "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/hooks/useToast.ts"
    click Utils "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/lib/utils.ts"
    click WalletIntegration "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/components/Connect.tsx"

    %% External Services & Assets
    click StaticAssets "https://github.com/sanidhyarathore/teamverse-frontend/tree/main/public"
    click CI_CD "https://github.com/sanidhyarathore/teamverse-frontend/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef state fill:#DFFFE0,stroke:#2F8F2F,stroke-width:1px;
    classDef external fill:#FFE5B4,stroke:#D97504,stroke-width:1px;
```
