# ry-animal/valkyriefinance architecture

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

- Interactive diagram: https://gitdiagram.com/ry-animal/valkyriefinance
- Repository: https://github.com/ry-animal/valkyriefinance

## Overview

##### Project Type & Purpose
- This is a full-stack, monorepo-based DeFi application (“Valkyrie Finance”) combining:
- A Next.js/React web frontend (apps/web) with Web3 integration
- A tRPC-based Node.js/TypeScript API server (apps/server)
- A Go-based AI microservice for real-time portfolio optimization (apps/ai-engine)
- A Storybook host for UI components (apps/storybook-host)
- Shared libraries for UI, config, common utilities, and Solidity contracts under packages/
- Goals: enable wallet-based auth, on-chain vault interaction (ERC-4626), portfolio optimization via AI, real-time data and analytics, CI/CD to Vercel, and multi-chain support.

##### File-Structure Analysis & Architectural Patterns
- Top-level directories:
- apps/ — deployable services: web, server, ai-engine, storybook
- packages/ — libraries: ui (component library), common (shared schemas & utilities), config (network & env), contracts (Solidity + Foundry)
- scripts/, docs/, tooling (pnpm-workspace, turbo, Biome)
- Pattern: microservices + modular monorepo + layered architecture (UI → API → services → data)
- Key config/deployment files: turbo.json, pnpm-workspace.yaml, Vercel config, GitHub Actions workflows, Docker instructions for AI engine.

##### Main Components
a. Frontend Layer (apps/web)
- Next.js app: pages & app router, React components, Tailwind CSS, Web3 hooks (wagmi), calls:
- tRPC API endpoints (apps/server)
- On-chain smart contract methods via Viem/Reown AppKit
- AI Engine HTTP/gRPC endpoint for optimization
b. API Layer (apps/server)
- Next.js API + tRPC routers: auth, portfolio, staking, vault, ai, etc.
- Drizzle ORM → PostgreSQL
- Middleware: rate limiting, CORS, context injection, Redis caching
c. AI Engine (apps/ai-engine)
- Go service exposing AI gRPC/REST (proto/ai_service.proto)
- Data collectors: real-time market feeds → Enhanced AI algorithms → responses
d. Data & Persistence
- PostgreSQL with Drizzle ORM, migrations under src/db
- Redis for caching/rate-limit
- On-chain state via Ethereum networks (Sepolia, Ethereum mainnet, Arbitrum, Optimism)
e. Smart Contracts (packages/contracts)
- Solidity contracts (ERC-20, ERC-4626 vault), tested and deployed via Foundry
f. Developer Docs & UI Library
- Storybook host (apps/storybook-host) for component previews
- packages/ui: design tokens, Tailwind config
- packages/common & config: shared types, schemas, network constants

##### Component Interactions & Data Flows
1. User → Web Frontend
- Authenticate via wallet (ConnectKit/Reown AppKit)
- UI triggers – on-chain calls or API calls
2. Web Frontend → API Server (tRPC over HTTPS)
- Portfolio queries, portfolio modifications (vault deposit/withdraw)
- Server calls Drizzle → PostgreSQL
- Server may call AI Engine for optimization suggestions
3. Web Frontend → On-Chain Contracts (using Wagmi/Viem)
- Direct deposit/withdraw transactions
- Read vault balances or token info
4. API Server → AI Engine (HTTP/gRPC)
- Sub-20ms portfolio optimization requests → responses back to frontend or server
5. AI Engine → Market Data Feeds
- Real data collector service fetches live prices and metrics
6. API Server → Redis
- Caching hot responses (e.g., market snapshots, AI results)
7. CI/CD & Deployment
- GitHub Actions build & deploy Storybook, frontend, server to Vercel
- Docker build & push AI Engine

##### Architectural Patterns & Design Principles
- Microservices: each app folder is independently deployable
- Monorepo / pnpm workspaces: shared code and uniform versioning
- Layered architecture: Presentation (web) → API → Services (AI, data collector) → Persistence
- Hexagonal/Ports & Adapters: AI Engine has a defined proto interface; server depends only on that interface
- Eventual consistency: caching via Redis, on-chain state sync
- Type-safe end-to-end: tRPC, shared TypeScript schemas (packages/common)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::actor

    %% Frontend Layer
    subgraph "Frontend Layer"
        WebApp["Web App\nNext.js + React + Wagmi"]:::frontend
        AppEntry["App Entry & Routing"]:::frontend
        WagmiConfig["Web3 Integration\nwagmi-config.ts"]:::frontend
        UIComponents["UI Components & Pages"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        APIServer["API Server\nNode.js + tRPC + Drizzle ORM"]:::backend
        Routers["tRPC Routers"]:::backend
        RouteHandler["Next.js API Route Handler"]:::backend
        DrizzleConfig["Drizzle Config"]:::backend
        DBSchema["DB Schema & Queries"]:::backend
        Migrations["DB Migrations"]:::backend
        Middleware["Middleware & Redis Lib"]:::backend
    end

    %% AI Service
    subgraph "AI Service"
        AIEngine["AI Engine\nGo + gRPC + Data Collector"]:::ai
        Proto["Proto Definition"]:::ai
        AIService["AI Logic & Collector"]:::ai
        SimpleServer["Server Implementation"]:::ai
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::db
        Redis["Redis"]:::db
    end

    %% Blockchain Networks
    subgraph "Blockchain Networks"
        Ethereum["Ethereum Mainnet\nSepolia, Arbitrum, Optimism"]:::chain
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        UIlib["packages/ui"]:::lib
        Common["packages/common"]:::lib
        Config["packages/config"]:::lib
        Contracts["packages/contracts"]:::lib
    end

    %% CI/CD & Tooling
    subgraph "CI/CD & Tooling"
        GitHubActions["GitHub Actions"]:::tool
        Vercel["Vercel Deployment"]:::tool
        Docker["Docker for AI Engine"]:::tool
    end

    %% Flows
    User -->|"Interacts"| WebApp
    WebApp -->|"tRPC over HTTPS"| APIServer
    WebApp -->|"RPC Calls"| Ethereum
    APIServer -->|"Drizzle ORM"| Postgres
    APIServer -->|"Cache & Rate-Limit"| Redis
    APIServer -->|"gRPC/HTTP"| AIEngine
    AIEngine -->|"Fetches Live Data"| MarketFeed["Market Data Feeds"]:::ext
    MarketFeed -.->|"Live Price Stream"| AIService
    AIService -->|"Optimized Response"| AIEngine
    AIEngine -->|"Returns Optimization"| APIServer

    %% CI/CD flows
    GitHubActions -->|Build & Deploy| WebApp
    GitHubActions -->|Build & Deploy| APIServer
    GitHubActions -->|Build & Publish Docker| Docker
    Vercel -->|Hosts| WebApp
    Vercel -->|Hosts| APIServer

    %% Library Dependencies
    UIlib -.-> WebApp
    UIlib -.-> Storybook["Storybook Host"]:::frontend
    Common -.-> WebApp
    Common -.-> APIServer
    Common -.-> AIEngine
    Config -.-> WebApp
    Config -.-> APIServer
    Config -.-> AIEngine
    Contracts -.-> WebApp
    Contracts -.-> APIServer

    %% Storybook Host
    Storybook["Storybook Host\nComponent Preview"]:::frontend

    %% Click Events
    click WebApp "https://github.com/ry-animal/valkyriefinance/tree/main/apps/web"
    click AppEntry "https://github.com/ry-animal/valkyriefinance/tree/main/apps/web/src/app"
    click WagmiConfig "https://github.com/ry-animal/valkyriefinance/blob/main/apps/web/src/lib/wagmi-config.ts"
    click UIComponents "https://github.com/ry-animal/valkyriefinance/tree/main/apps/web/src/components"
    click Routers "https://github.com/ry-animal/valkyriefinance/tree/main/apps/server/src/routers"
    click RouteHandler "https://github.com/ry-animal/valkyriefinance/blob/main/apps/server/src/app/trpc/[trpc]/route.ts"
    click DrizzleConfig "https://github.com/ry-animal/valkyriefinance/blob/main/apps/server/drizzle.config.ts"
    click DBSchema "https://github.com/ry-animal/valkyriefinance/tree/main/apps/server/src/db/schema"
    click Migrations "https://github.com/ry-animal/valkyriefinance/tree/main/apps/server/src/db/migrations"
    click Middleware "https://github.com/ry-animal/valkyriefinance/blob/main/apps/server/src/lib/redis.ts"
    click Middleware "https://github.com/ry-animal/valkyriefinance/blob/main/apps/server/src/middleware/rate-limit.ts"
    click AIEngine "https://github.com/ry-animal/valkyriefinance/blob/main/apps/ai-engine/cmd/main.go"
    click AIEngine "https://github.com/ry-animal/valkyriefinance/blob/main/apps/ai-engine/main.go"
    click Proto "https://github.com/ry-animal/valkyriefinance/blob/main/apps/ai-engine/proto/ai_service.proto"
    click AIService "https://github.com/ry-animal/valkyriefinance/tree/main/apps/ai-engine/internal/services"
    click SimpleServer "https://github.com/ry-animal/valkyriefinance/blob/main/apps/ai-engine/internal/server/simple_server.go"
    click UIlib "https://github.com/ry-animal/valkyriefinance/tree/main/packages/ui"
    click Common "https://github.com/ry-animal/valkyriefinance/tree/main/packages/common"
    click Config "https://github.com/ry-animal/valkyriefinance/tree/main/packages/config"
    click Contracts "https://github.com/ry-animal/valkyriefinance/tree/main/packages/contracts"
    click GitHubActions "https://github.com/ry-animal/valkyriefinance/tree/main/.github/workflows"
    click Vercel "https://github.com/ry-animal/valkyriefinance/blob/main/vercel.json"
    click Docker "https://github.com/ry-animal/valkyriefinance/tree/main/apps/ai-engine/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFED,stroke:#28A745,color:#28A745
    classDef ai fill:#FFE8CC,stroke:#FF8C00,color:#FF8C00
    classDef db fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef chain fill:#F3E8FF,stroke:#6F42C1,color:#6F42C1
    classDef lib fill:#FFF5E6,stroke:#D69E2E,color:#D69E2E
    classDef tool fill:#E8F0FE,stroke:#1A73E8,color:#1A73E8
    classDef actor fill:#FFFFFF,stroke:#24292E,color:#24292E
    classDef ext fill:#F9FAFB,stroke:#959DA5,color:#959DA5
```
