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](./project-overview.md) - Architecture and features
- [Data Models](./data-models.md) - Database schema
- [API Contracts](./api-contracts.md) - Endpoints and actions
- [Development Guide](./development-guide.md) - Setup instructions