feat: add federated database support and update environment configuration

Author: williamluke4

.env.example

@@ -1 +1,2 @@
-DATABASE_URL=""
+DATABASE_URL=""
+FEDERATED_DB_URL="

CLAUDE.md

@@ -0,0 +1,120 @@
+# Sarafu Network Visualizer
+
+A Next.js application that visualizes blockchain transaction data from the Sarafu Network using interactive 2D and 3D force-directed graphs.
+
+## AI Team Configuration (autogenerated by team-configurator, 2025-12-05)
+
+**Important: YOU MUST USE subagents when available for the task.**
+
+### Detected Tech Stack
+
+- **Frontend Framework**: Next.js 13.4 (Pages Router) with React 18.2
+- **UI Styling**: Tailwind CSS 3.3 (JIT mode) with HeadlessUI and Framer Motion
+- **Visualization**: 
+  - 3D Force Graph 1.71
+  - React Force Graph 2D/3D (1.25/1.23)
+  - Three.js 0.153 with three-forcegraph
+- **Database**: PostgreSQL with Kysely 0.25 (type-safe SQL query builder)
+  - Multiple databases: Graph DB and Federated DB
+  - Type generation via kysely-codegen
+- **Caching**: Upstash Redis 1.35
+- **Blockchain**: viem 2.41, web3 4.0, multicoin-address-validator
+- **Data Fetching**: SWR 2.2
+- **Language**: TypeScript 5.4 (strict mode disabled)
+- **Testing**: Jest 29.5
+- **Build Tools**: ESBuild 0.18, PostCSS, Autoprefixer
+- **Deployment**: Vercel (@vercel/node 2.7)
+
+### Specialist Agents for This Project
+
+Use these specialists based on the task at hand:
+
+| Task | Agent | Notes |
+|------|-------|-------|
+| **Next.js SSR/SSG/API Routes** | `@react-nextjs-expert` | Primary specialist for Next.js features, pages, API routes, data fetching patterns, and optimization. Always check latest Next.js docs before implementing. |
+| **UI Components & Tailwind Styling** | `@tailwind-frontend-expert` | Utility-first styling, responsive design, container queries. Use for all component styling work. |
+| **Frontend Components (General)** | `@frontend-developer` | Alternative for React components when Next.js-specific features not needed. Use for client-side logic and state management. |
+| **API Design & Contracts** | `@api-architect` | Design REST endpoints, define request/response schemas, pagination strategies, error handling patterns. |
+| **Backend/Database Logic** | `@backend-developer` | PostgreSQL queries with Kysely, database migrations, data processing, caching strategies with Redis. |
+| **Code Reviews & Quality** | `@code-reviewer` | MUST USE before merging features or PRs. Provides security, maintainability, and performance reviews. |
+| **Performance Optimization** | `@performance-optimizer` | MUST USE for graph rendering performance, data processing optimization, bundle size reduction, caching strategies. |
+| **Documentation** | `@documentation-specialist` | Update README, API docs, architecture guides. Use after major features or when onboarding. |
+| **Codebase Analysis** | `@code-archaeologist` | Deep exploration of unfamiliar code, legacy analysis, architecture documentation, risk assessment. |
+
+### Project-Specific Guidance
+
+#### Graph Visualization Work
+- **Primary concerns**: Performance with large datasets, rendering optimization, user interactivity
+- **Key files**: 
+  - `/Users/chui/Dev/grassroots/vis/components/network-graph/` - Graph components
+  - `/Users/chui/Dev/grassroots/vis/utils/render_graph.ts` - Graph data generation logic
+- **Recommended agents**: `@performance-optimizer` for rendering performance, `@react-nextjs-expert` for component architecture, `@frontend-developer` for Three.js/D3 integration
+
+#### Database & Data Processing
+- **Stack**: PostgreSQL with Kysely ORM, multiple database connections (graphDB, federatedDB)
+- **Key files**:
+  - `/Users/chui/Dev/grassroots/vis/db/db.ts` - Database connections
+  - `/Users/chui/Dev/grassroots/vis/db/graph-db.d.ts` - Auto-generated types (regenerate with `npm run generate:graph`)
+  - `/Users/chui/Dev/grassroots/vis/db/federated-db.d.ts` - Auto-generated types
+- **Recommended agents**: `@backend-developer` for query optimization and data layer work, `@api-architect` for API contract design
+
+#### API Routes
+- **Pattern**: Next.js API routes in `/Users/chui/Dev/grassroots/vis/pages/api/`
+- **Current routes**: 
+  - `/api/data` - Main graph data endpoint with caching
+- **Recommended agents**: `@react-nextjs-expert` for Next.js-specific API features, `@api-architect` for endpoint design, `@backend-developer` for data processing
+
+#### Styling & Components
+- **Style system**: Tailwind CSS with JIT mode, HeadlessUI for accessible components
+- **Animation**: Framer Motion for transitions
+- **Key files**: `/Users/chui/Dev/grassroots/vis/tailwind.config.js`
+- **Recommended agents**: `@tailwind-frontend-expert` for all styling work, `@frontend-developer` for component logic
+
+#### Performance Considerations
+- Large dataset visualization (blockchain transactions)
+- Redis caching with 24-hour TTL
+- Graph data processing optimization (using Maps for O(1) lookups)
+- Dynamic imports for heavy visualization libraries
+- **Recommended agent**: `@performance-optimizer` for any performance work
+
+#### Blockchain Integration
+- Multiple blockchain libraries (viem, web3.js)
+- Address validation with multicoin-address-validator
+- Token transfer tracking and voucher system
+- **Recommended agents**: `@backend-developer` for blockchain data processing, `@code-reviewer` for security review of blockchain interactions
+
+### Workflow Recommendations
+
+1. **New Features**: Start with `@react-nextjs-expert` or `@api-architect` depending on frontend vs backend
+2. **Performance Issues**: Always consult `@performance-optimizer` for graph rendering or data processing bottlenecks
+3. **Before Merging**: ALWAYS run `@code-reviewer` for security and quality checks
+4. **Complex Queries**: Use `@backend-developer` for Kysely query optimization
+5. **UI/UX Work**: Use `@tailwind-frontend-expert` for styling, `@frontend-developer` for component logic
+6. **Documentation**: After major changes, use `@documentation-specialist` to update docs
+
+### Example Commands
+
+```bash
+# Next.js feature development
+"@react-nextjs-expert Build a new API route for filtering graph data by date range"
+
+# Performance optimization
+"@performance-optimizer Analyze and optimize the graph rendering performance in network-graph-3d.tsx"
+
+# Styling work
+"@tailwind-frontend-expert Create a responsive header component with dark mode support"
+
+# Code review before PR
+"@code-reviewer Review the changes in pages/api/data.ts and utils/cache.ts for security and performance"
+
+# Database optimization
+"@backend-developer Optimize the transaction query in pages/api/data.ts to reduce load time"
+
+# Architecture analysis
+"@code-archaeologist Analyze the graph data processing pipeline and document the architecture"
+```
+
+---
+
+**Last Updated**: 2025-12-05  
+**Configured By**: team-configurator agent

KV_SETUP.md

@@ -6,12 +6,12 @@
 Requires DATABASE_URL to be set
 
 ```
-yarn && yarn dev
+pnpm && pnpm dev
 ```
 
 ## Build
 
 ```
-yarn && yarn build
-yarn start
+pnpm && pnpm build
+pnpm start
 ```

README.md

@@ -0,0 +1,90 @@
+export const PlayIcon = ({ onClick }) => {
+  return (
+    <svg
+      className="w-8 h-8 p-2 z-10 cursor-pointer"
+      viewBox="0 0 60 60"
+      onClick={onClick}
+      stroke="white"
+      fill="white"
+    >
+      <polygon points="0,0 50,30 0,60" />
+    </svg>
+  );
+};
+export const PauseIcon = ({ onClick }) => {
+  return (
+    <svg
+      className="w-8 h-8 p-2 center z-10 cursor-pointer"
+      viewBox="0 0 60 60"
+      stroke="white"
+      fill="white"
+      onClick={onClick}
+    >
+      <polygon points="0,0 15,0 15,60 0,60" />
+      <polygon points="25,0 40,0 40,60 25,60" />
+    </svg>
+  );
+};
+export function GearIcon(props: { onClick: () => void }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+      strokeWidth={1.5}
+      stroke="white"
+      className="w-10 h-10 p-2 z-10 cursor-pointer"
+      onClick={() => props.onClick()}
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.324.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 011.37.49l1.296 2.247a1.125 1.125 0 01-.26 1.431l-1.003.827c-.293.24-.438.613-.431.992a6.759 6.759 0 010 .255c-.007.378.138.75.43.99l1.005.828c.424.35.534.954.26 1.43l-1.298 2.247a1.125 1.125 0 01-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.57 6.57 0 01-.22.128c-.331.183-.581.495-.644.869l-.213 1.28c-.09.543-.56.941-1.11.941h-2.594c-.55 0-1.02-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 01-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 01-1.369-.49l-1.297-2.247a1.125 1.125 0 01.26-1.431l1.004-.827c.292-.24.437-.613.43-.992a6.932 6.932 0 010-.255c.007-.378-.138-.75-.43-.99l-1.004-.828a1.125 1.125 0 01-.26-1.43l1.297-2.247a1.125 1.125 0 011.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.087.22-.128.332-.183.582-.495.644-.869l.214-1.281z"
+      />
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+      />
+    </svg>
+  );
+}
+
+export function CloseIcon(props: { onClick: () => void; className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+      strokeWidth={2}
+      stroke="currentColor"
+      className={props.className || "w-5 h-5 cursor-pointer text-gray-500 hover:text-gray-700 transition-colors"}
+      onClick={props.onClick}
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M6 18L18 6M6 6l12 12"
+      />
+    </svg>
+  );
+}
+
+export function ChevronDownIcon(props: { className?: string }) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      fill="none"
+      viewBox="0 0 24 24"
+      strokeWidth={2}
+      stroke="currentColor"
+      className={props.className || "w-4 h-4"}
+    >
+      <path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M19 9l-7 7-7-7"
+      />
+    </svg>
+  );
+}