How ry-animal/valkyriefinance works
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)