docs/source-tree.md

Vault - Source Tree Analysis

Generated: 2026-02-11
Project Root: /

---

Root Directory Structure

vault/
├── .github/                    # GitHub workflows and configuration
│   └── workflows/
│       └── deploy.yml          # CI/CD: Build, test, deploy to Vercel + Railway
│
├── .husky/                     # Git hooks (pre-commit linting)
│
├── _bmad/                      # BMAD methodology configuration
│   ├── _config/                # Manifests and configuration
│   ├── bmm/                    # BMAD Method Module
│   └── core/                   # BMAD Core Module
│
├── _bmad-output/               # BMAD-generated artifacts
│   ├── planning-artifacts/     # PRD, Architecture, Epics, Product Brief
│   └── implementation-artifacts/ # Sprint status, story files
│
├── docs/                       # Project documentation (this documentation)
│
├── drizzle/                    # Database migrations
│   └── *.sql                   # Migration files
│
├── legacy_configs/             # Legacy deployment configurations
│   └── fly/                    # Fly.io configs (deprecated)
│
├── public/                     # Static assets
│
├── src/                        # Source code (main application)
│   ├── app/                    # Next.js 15 App Router
│   ├── components/             # Shared UI components
│   ├── features/               # Feature-based modules
│   ├── inngest/                # Background job functions
│   ├── lib/                    # Core utilities
│   ├── config/                 # Application configuration
│   └── types/                  # TypeScript type definitions
│
├── supabase/                   # Supabase configuration
│
├── package.json                # Dependencies and scripts
├── tsconfig.json               # TypeScript configuration
├── next.config.ts              # Next.js configuration
├── drizzle.config.ts           # Drizzle ORM configuration
├── tailwind.config.ts          # Tailwind CSS configuration
├── vitest.config.ts            # Vitest test configuration
├── eslint.config.mjs           # ESLint configuration
├── Dockerfile                  # Docker configuration (Hugging Face Spaces)
└── vercel.json                 # Vercel deployment configuration

---

Source Code Structure (src/)

App Router (src/app/)

Next.js 15 App Router pages and API routes.

src/app/
├── layout.tsx                  # Root layout (theme, fonts, toaster)
├── page.tsx                    # Homepage (public landing)
├── globals.css                 # Global styles (Tailwind)
├── favicon.ico                 # Site favicon
│
├── api/                        # API Route Handlers
│   ├── auth/[...all]/route.ts  # Better Auth endpoints
│   ├── inngest/route.ts        # Inngest webhook handler
│   ├── health/route.ts         # Health check endpoint
│   ├── manual-trigger/route.ts # Manual workflow triggers (dev)
│   └── youtube/
│       ├── callback/route.ts   # YouTube OAuth callback
│       ├── connect/route.ts    # Initiate YouTube connection
│       └── disconnect/route.ts # Disconnect YouTube channel
│
├── login/
│   └── page.tsx                # Login page
│
├── register/
│   └── page.tsx                # Registration page
│
├── dashboard/                  # Creator Dashboard
│   ├── page.tsx                # Main dashboard (videos, metrics)
│   ├── moderation/
│   │   └── page.tsx            # Moderation queue
│   ├── requests/
│   │   └── page.tsx            # Product requests & proposals
│   └── fix-channels/
│       └── page.tsx            # Channel repair utility
│
├── admin/                      # Admin Operations
│   ├── page.tsx                # Redirects to /admin/dashboard
│   ├── layout.tsx              # Admin layout with navigation
│   ├── dashboard/
│   │   └── page.tsx            # Platform overview
│   ├── moderation/
│   │   └── page.tsx            # Admin moderation queue
│   ├── analysis-queue/
│   │   └── page.tsx            # Video analysis queue
│   ├── analysis/[id]/
│   │   └── page.tsx            # Individual analysis detail
│   ├── requests/
│   │   └── page.tsx            # Request hub (proposals, requests)
│   └── users/
│       └── page.tsx            # User management
│
├── vault/[creatorSlug]/        # Public Creator Vault
│   ├── page.tsx                # Vault grid (SSR/ISR)
│   └── product/[productId]/
│       └── page.tsx            # Product detail page
│
├── showcase/                   # Demo/Showcase Mode
│   ├── page.tsx                # Featured creators grid
│   └── [videoId]/
│       ├── page.tsx            # Video showcase
│       └── moderate/
│           └── page.tsx        # Showcase moderation
│
├── creators/
│   └── page.tsx                # Creator discovery
│
├── design/
│   └── page.tsx                # Design system preview
│
└── unsubscribe/[token]/
    └── page.tsx                # Email unsubscribe

Components (src/components/)

Shared UI components (shadcn/ui based).

src/components/
├── mode-toggle.tsx             # Dark/light theme toggle
├── theme-provider.tsx          # Theme context provider
│
├── auth/
│   ├── sign-in-form.tsx        # Login form
│   ├── sign-up-form.tsx        # Registration form
│   ├── user-nav.tsx            # User avatar dropdown
│   └── auto-claimer.tsx        # Auto-claim vault ownership
│
└── ui/                         # shadcn/ui components
    ├── alert-dialog.tsx
    ├── alert.tsx
    ├── avatar.tsx
    ├── badge.tsx
    ├── button.tsx
    ├── card.tsx
    ├── checkbox.tsx
    ├── dialog.tsx
    ├── dropdown-menu.tsx
    ├── input.tsx
    ├── label.tsx
    ├── scroll-area.tsx
    ├── select.tsx
    ├── separator.tsx
    ├── skeleton.tsx
    ├── sonner.tsx              # Toast notifications
    ├── tabs.tsx
    └── textarea.tsx

Feature Modules (src/features/)

Feature-based organization for business logic.

src/features/
│
├── analytics/                  # Metrics and tracking
│   └── components/
│       └── key-metrics-row.tsx # Dashboard metrics display
│
├── discovery/                  # AI Video Scanning
│   ├── actions/
│   │   └── connect-youtube.ts  # YouTube OAuth action
│   ├── components/
│   │   └── youtube-connect-section.tsx
│   └── services/
│       ├── youtube-videos.service.ts  # YouTube Data API
│       ├── frame-extraction.service.ts # FFmpeg processing
│       ├── ai-vision.service.ts        # Vision provider abstraction
│       ├── vision-provider.factory.ts  # Provider factory
│       ├── storage.service.ts          # Supabase storage
│       └── providers/
│           ├── vision-provider.interface.ts
│           ├── gemini.provider.ts
│           └── huggingface.provider.ts
│
├── interest/                   # "I Want This" Feature
│   ├── actions/
│   │   └── create-interest-pledge.ts
│   ├── components/
│   │   └── interest-capture-modal.tsx
│   └── types/
│       └── interest.types.ts
│
├── marketplace/                # Marketplace Integration
│   ├── actions/
│   │   ├── trigger-marketplace-match.ts
│   │   └── trigger-link-health-check.ts
│   └── services/
│       ├── amazon.service.ts   # Amazon PA-API
│       ├── ebay.service.ts     # eBay Finding API
│       ├── etsy.service.ts     # Etsy Open API
│       ├── errors.ts           # Custom errors
│       ├── link-health.service.ts
│       └── marketplace-cache.service.ts
│
├── moderation/                 # Creator Moderation
│   ├── actions/
│   │   ├── approve-detection.ts
│   │   ├── reject-detection.ts
│   │   ├── bulk-approve.ts
│   │   ├── bulk-reject.ts
│   │   ├── edit-detection.ts
│   │   ├── delete-detection.ts
│   │   ├── add-detection.ts
│   │   ├── admin-correct-detection.ts
│   │   ├── admin-mark-incorrect.ts
│   │   ├── fetch-product-metadata.ts
│   │   ├── handle-proposal.ts
│   │   ├── transfer-temporary-products.ts
│   │   └── upload-product-image.ts
│   ├── components/
│   │   ├── moderation-queue.tsx
│   │   ├── admin-moderation-queue.tsx
│   │   ├── admin-detection-card.tsx
│   │   ├── edit-detection-dialog.tsx
│   │   ├── add-product-dialog.tsx
│   │   ├── product-form.tsx
│   │   ├── image-upload-field.tsx
│   │   ├── admin-correction-modal.tsx
│   │   └── admin-mark-incorrect-modal.tsx
│   ├── services/
│   │   ├── moderation.service.ts
│   │   └── admin-moderation.service.ts
│   └── utils/
│       └── demo.ts             # Demo mode utilities
│
├── vault/                      # Public Vault Experience
│   ├── actions/
│   │   ├── add-to-workbench.ts
│   │   ├── quick-analyze.ts
│   │   ├── redirect-to-marketplace.ts
│   │   ├── refresh-metadata.ts
│   │   ├── search-products.ts
│   │   └── trigger-analysis.ts
│   ├── components/
│   │   ├── vault-grid.tsx      # Main product grid
│   │   ├── vault-header.tsx    # Creator info header
│   │   ├── vault-filters.tsx   # Filter controls
│   │   ├── vault-grid-skeleton.tsx
│   │   ├── vault-grid-with-temp-products.tsx
│   │   ├── product-card.tsx    # Individual product
│   │   ├── product-grid.tsx
│   │   ├── product-card-skeleton.tsx
│   │   ├── product-request-dialog.tsx
│   │   ├── category-filter.tsx
│   │   ├── search-bar.tsx
│   │   ├── search-results.tsx
│   │   ├── video-card.tsx
│   │   ├── video-embed.tsx
│   │   ├── discovery-panel.tsx
│   │   ├── claim-handler.tsx
│   │   ├── claim-vault-button.tsx
│   │   ├── unauthenticated-banner.tsx
│   │   ├── affiliate-submission-dialog.tsx
│   │   ├── quick-analyze-tool.tsx
│   │   └── add-to-workbench-button.tsx
│   ├── services/
│   │   ├── vault.service.ts    # Data fetching + caching
│   │   ├── showcase.service.ts
│   │   └── click-tracking.service.ts
│   ├── hooks/
│   │   └── use-temporary-products.ts
│   ├── config/
│   │   ├── demo-config.ts
│   │   └── sample-data.ts
│   └── types/
│       └── vault.types.ts
│
├── admin/                      # Admin Operations
│   └── actions/
│       └── stats.ts            # Platform statistics
│
└── dashboard/                  # Creator Dashboard
    ├── actions/
    │   └── fetch-videos.ts
    └── components/
        └── video-workbench.tsx

Inngest Functions (src/inngest/)

Background job orchestration.

src/inngest/
├── client.ts                   # Inngest client configuration
│
└── functions/
    ├── scan-video-archive.ts   # YouTube archive scanning
    ├── detect-objects.ts       # AI object detection
    ├── match-marketplace.ts    # Marketplace matching
    ├── monitor-link-health.ts  # Link health monitoring
    ├── social-healing.ts       # Social metadata repair
    └── warm-featured-creators-cache.ts

Core Libraries (src/lib/)

Core utilities and configurations.

src/lib/
├── auth.ts                     # Better Auth configuration
├── auth-client.ts              # Client-side auth utilities
├── admin.ts                    # Admin utilities
├── redis.ts                    # Upstash Redis client
│
└── db/
    ├── index.ts                # Drizzle client
    └── schema.ts               # Database schema (590 lines)

Configuration (src/config/)

Application configuration files.

src/config/
└── vision.config.ts            # AI vision provider config

---

Configuration Files

Root Configuration

File	Purpose
package.json	Dependencies, scripts, npm configuration
tsconfig.json	TypeScript compiler options
next.config.ts	Next.js configuration (images, externals, Sentry)
drizzle.config.ts	Drizzle ORM configuration
tailwind.config.ts	Tailwind CSS configuration
vitest.config.ts	Vitest test runner configuration
eslint.config.mjs	ESLint rules and plugins
vercel.json	Vercel deployment settings
Dockerfile	Docker image for Hugging Face Spaces

Environment Variables

Required environment variables (see .env.example):

# Database
DATABASE_URL=
DIRECT_URL=

# Authentication
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Inngest
INNGEST_EVENT_KEY=
INNGEST_SIGNING_KEY=

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

# Redis
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# AI/Vision
GEMINI_API_KEY=
HUGGINGFACE_API_KEY=
VISION_PROVIDER=gemini|huggingface

# Marketplaces
AMAZON_ACCESS_KEY=
AMAZON_SECRET_KEY=
AMAZON_AFFILIATE_TAG=
EBAY_APP_ID=
EBAY_CERT_ID=
EBAY_CAMPAIGN_ID=
ETSY_API_KEY=

# Monitoring
SENTRY_ORG=
SENTRY_PROJECT=

# Admin
ADMIN_EMAILS=

---

Key Entry Points

Entry Point	Description
src/app/layout.tsx	Root layout, theme provider
src/app/page.tsx	Homepage
src/app/api/inngest/route.ts	Inngest webhook handler
src/inngest/client.ts	Background job client
src/lib/db/index.ts	Database connection
src/lib/auth.ts	Authentication setup

---

Related Documentation

• Project Overview - Architecture and features
• Data Models - Database schema
• API Contracts - Endpoints and actions
• Development Guide - Setup instructions