# prisma/ - Database Layer

<!-- Parent: ../AGENTS.md -->

## OVERVIEW

Prisma ORM configuration for PostgreSQL (Neon serverless) with multilingual support, vector embeddings, and automated workflows integration.

## KEY FILES

| File | Purpose |
|------|---------|
| `schema.prisma` | Database models, enums, indexes |
| `seed.ts` | Initial data seeding script |
| `migrations/` | Migration history |

## DATABASE MODELS

### Core Models

| Model | Purpose | Key Fields |
|-------|---------|------------|
| `Project` | AI projects | name/nameEn, slug (unique), description, content, embedding (vector) |
| `Tag` | Project tags | name (unique), slug (unique) |
| `ExternalLink` | Project links | type (WEBSITE/GITHUB/HUGGINGFACE/PAPER), url |
| `ProjectTag` | Junction table | projectId, tagId |

### Keyword Cloud System

| Model | Purpose |
|-------|---------|
| `Quarter` | Quarterly metadata |
| `Keyword` | Trending keywords with visual config |
| `VisualStyleRule` | Color/size/border rules by score range |
| `KeywordCloudErrorLog` | Error tracking for n8n workflows |

### Discovery System

| Model | Purpose |
|-------|---------|
| `ProjectDiscoveryTask` | Exploration task tracking |

### AI Timeline System

| Model | Purpose |
|-------|---------|
| `AIEvent` | Historical AI events with dates |

## ENUMS

- `ProjectStatus`: ACTIVE | ARCHIVED
- `LinkType`: WEBSITE | GITHUB | HUGGINGFACE | PAPER
- `TaskStatus`: PENDING | IN_PROGRESS | COMPLETED | FAILED

## INDEXES

| Index | Model | Purpose |
|-------|-------|---------|
| `idx_project_slug` | Project | Unique slug lookup |
| `idx_project_status_createdAt` | Project | Filter by status, sort by date |
| `idx_project_embedding_cosine` | Project | Vector similarity search |
| `idx_link_type_url` | ExternalLink | URL deduplication |
| `idx_task_status_created` | ProjectDiscoveryTask | Task queue queries |
| `idx_keyword_quarterId` | Keyword | Quarterly keyword lookup |
| `idx_quarter_displayOrder` | Quarter | Quarter ordering |

## MULTILINGUAL PATTERN

Most models follow the dual-language pattern:
```
name: String         // Chinese (primary)
nameEn: String?      // English (optional)

description: String
descriptionEn: String?

content: String?
contentEn: String?
```

## CASCADE DELETIONS

- `ExternalLink` → `Project` (onDelete: Cascade)
- `ProjectTag` → `Project` and `Tag` (onDelete: Cascade)
- `Keyword` → `Quarter` (onDelete: Cascade)

## FOR AI AGENTS

### Working With This Directory

1. **After schema changes**:
   ```bash
   pnpm prisma migrate dev --name description
   pnpm prisma generate
   ```

2. **Seed database**:
   ```bash
   pnpm prisma db seed
   ```

3. **Inspect database**:
   ```bash
   pnpm prisma studio
   ```

### Common Patterns

- **Unique constraints**: Handle with try-catch + fallback (see webhook tag upsert)
- **Multilingual queries**: Always check both `field` and `fieldEn` variants
- **Vector search**: Use `Unsupported("vector")` type with pgvector extension

### Anti-Patterns

- NEVER modify schema without running migrations
- NEVER skip `pnpm prisma generate` after schema changes
- NEVER use raw SQL when Prisma methods are available
- NEVER commit `.env` files with DATABASE_URL

## N8N INTEGRATION

n8n workflows interact with these models:
- **Keywords**: Written by keyword-cloud workflow
- **ProjectDiscoveryTask**: Created by trending/topic workflows
- **Project**: Updated by analysis workflows
- **Tag**: Maintained by tag-janitor workflow

<!-- MANUAL: Additional notes can be added below -->