# speclock/specklock architecture

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

## Overview

##### Project Type & Purpose
- Project Type: A full-stack decentralized application focusing on blockchain-based project management.
- Purpose: To enable secure, transparent collaboration via smart contracts on Avalanche Fuji Testnet. It handles project creation, milestone funding, role-based access (client/developer), and wallet integration while providing a responsive, theme-aware UI.

##### Analyzing the File Structure
- Frontend Code: Located inside the src/ directory, it is organized by concerns:
- Components (UI elements such as Layout.tsx)
- Contexts (for managing global state: ThemeContext.tsx and WalletContext.tsx)
- Pages (UI routes: CreateProject, Dashboard, Profile, ProjectDetails)
- Services (smart contract interactions: contractService.tsx and projectContractService.tsx)
- Utilities and configuration files that include settings for Tailwind CSS, TypeScript, and Vite.
- Configuration & Build Files: Files like package.json, vite.config.ts, postcss.config.js indicate bundling and styling setups.
- The README further confirms the use of React 18, TypeScript, Tailwind, ethers.js, and blockchain-specific integrations.

##### Key Components & Their Relationships
a. Frontend UI Layer:
- Browser/client running a React application with an entry point (main.tsx) that sets up the UI.
- The Layout component is the central container hosting navigation and page rendering.
- Pages such as Dashboard, Profile, CreateProject, and ProjectDetails represent different functional views.

b. Global State Management:
- Contexts such as ThemeContext (for dark/light mode) and WalletContext (for blockchain wallet integrations like MetaMask) ensure data is shared across the UI.

c. Blockchain and Smart Contract Services:
- Services modules (contractService.tsx and projectContractService.tsx) handle communication with smart contracts using ethers.js.
- These modules connect to the Avalanche blockchain (Fuji Testnet) for managing project milestones, payments, and confirmations.

d. External Dependencies & Technologies:
- React and TypeScript drive the client-side logic.
- Tailwind CSS handles styling.
- ethers.js is responsible for blockchain interactions.
- MetaMask (or similar wallets) integrates with WalletContext for real-time network and balance updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend UI Layer
    subgraph "Frontend UI Layer"
        E["Entry Point (main.tsx)"]:::frontend
        A["Root Component (App.tsx)"]:::frontend
        L["Layout Component (Layout.tsx)"]:::frontend
        subgraph "UI Pages"
            CP["CreateProject Page (CreateProject.tsx)"]:::frontend
            D["Dashboard Page (Dashboard.tsx)"]:::frontend
            P["Profile Page (Profile.tsx)"]:::frontend
            PD["ProjectDetails Page (ProjectDetails.tsx)"]:::frontend
        end
    end

    %% Global State Management
    subgraph "Global State (React Contexts)"
        TC["ThemeContext (ThemeContext.tsx)"]:::globalState
        WC["WalletContext (WalletContext.tsx)"]:::globalState
    end

    %% Blockchain & Smart Contract Services
    subgraph "Blockchain Services (ethers.js)"
        CS["Contract Service (contractService.tsx)"]:::blockchain
        PCS["Project Contract Service (projectContractService.tsx)"]:::blockchain
    end

    %% Avalanche Network
    subgraph "Avalanche Network"
        AV["Avalanche Fuji Testnet"]:::external
    end

    %% Connections
    E --> A
    A --> L
    L --> CP
    L --> D
    L --> P
    L --> PD
    L --> TC
    L --> WC
    CP --> CS
    WC --> CS
    WC --> PCS
    CS --> AV
    PCS --> AV

    %% Click Events
    click E "https://github.com/speclock/specklock/blob/main/src/main.tsx"
    click A "https://github.com/speclock/specklock/blob/main/src/App.tsx"
    click L "https://github.com/speclock/specklock/blob/main/src/components/Layout.tsx"
    click CP "https://github.com/speclock/specklock/blob/main/src/pages/CreateProject.tsx"
    click D "https://github.com/speclock/specklock/blob/main/src/pages/Dashboard.tsx"
    click P "https://github.com/speclock/specklock/blob/main/src/pages/Profile.tsx"
    click PD "https://github.com/speclock/specklock/blob/main/src/pages/ProjectDetails.tsx"
    click TC "https://github.com/speclock/specklock/blob/main/src/contexts/ThemeContext.tsx"
    click WC "https://github.com/speclock/specklock/blob/main/src/contexts/WalletContext.tsx"
    click CS "https://github.com/speclock/specklock/blob/main/src/services/contractService.tsx"
    click PCS "https://github.com/speclock/specklock/blob/main/src/services/projectContractService.tsx"

    %% Styles
    classDef frontend fill:#ffde59,stroke:#d48806,stroke-width:2px;
    classDef globalState fill:#9cd1ff,stroke:#007acc,stroke-width:2px;
    classDef blockchain fill:#a2d149,stroke:#82b366,stroke-width:2px;
    classDef external fill:#ff9f9f,stroke:#e06666,stroke-width:2px;
```
