agent-park/prisma/AGENTS.md

prisma/ - Database Layer

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:

   pnpm prisma migrate dev --name description
   pnpm prisma generate
   

2. Seed database:

   pnpm prisma db seed
   

3. Inspect database:

   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