Skip to content

AGENTS.md

Latest commit

 

History

History
115 lines (95 loc) · 4.43 KB

AGENTS.md

File metadata and controls

115 lines (95 loc) · 4.43 KB
Raw

AGENTS.md

This file provides guidance to Verdent when working with code in this repository.

Table of Contents

  1. Commonly Used Commands
  2. High-Level Architecture & Structure
  3. Key Rules & Constraints
  4. Development Hints

Commands

  • npm run install:all - Install all dependencies (root, server, client)
  • npm run dev - Run both frontend (port 3000) and backend (port 3001) concurrently
  • npm run dev:server - Run only backend server with hot reload
  • npm run dev:client - Run only frontend with hot reload
  • npm run build - Build both client and server for production
  • npm start - Start production server (after build)

Architecture

Major Subsystems

  • Frontend (React + Vite): User interface with 3 main features
    • Generator: AI hook generation from topics
    • Analyzer: Hook scoring and feedback
    • Patterns: Template library browser
  • Backend (Express + TypeScript): REST API for AI operations and data persistence
    • Routes: API endpoints for hooks, patterns, history
    • Services: OpenAI integration for generation and analysis
    • Database: SQLite for storing hooks, patterns, and history
  • AI Layer: OpenAI GPT-4 for hook generation and analysis

Key Data Flows

  1. Hook Generation Flow:

    • User enters topic → Frontend sends POST to /api/hooks/generate
    • Backend calls OpenAI with prompt → Returns 5 hooks
    • Hooks saved to DB → Frontend displays results

  2. Hook Analysis Flow:

    • User pastes hook → Frontend sends POST to /api/hooks/analyze
    • Backend calls OpenAI for scoring → Parses score + feedback
    • Result saved to DB → Frontend displays score and suggestions

  3. Pattern Library Flow:

    • Frontend requests GET /api/hooks/patterns
    • Backend queries SQLite → Returns pre-seeded templates
    • Frontend displays filterable pattern cards

External Dependencies

  • OpenAI API (GPT-4) - requires OPENAI_API_KEY in server/.env
  • No authentication system implemented (JWT setup exists but unused)

Development Entry Points

  • Frontend: client/src/main.tsx → App.tsx
  • Backend: server/src/index.ts
  • API client: client/src/api.ts (axios-based)

Subsystem Relationships

graph TD
    A[React Frontend] -->|HTTP Requests| B[Express API]
    B -->|Prompts| C[OpenAI GPT-4]
    B -->|Read/Write| D[SQLite DB]
    A -->|Proxy /api| B
    D -->|Hooks Table| E[Generated Hooks]
    D -->|Patterns Table| F[Hook Templates]
Loading

Key Rules & Constraints

From Project Structure

  • Frontend runs on port 3000, backend on port 3001
  • Vite proxy configured to forward /api/* to backend
  • TypeScript strict mode enabled on both client and server
  • SQLite database auto-initialized on server start with 10 pre-seeded patterns

Environment Requirements

  • Node.js 18+ required
  • OpenAI API key is mandatory - app will fail without it
  • server/.env must be created from server/.env.example

Code Conventions [inferred]

  • React components use functional style with hooks
  • No prop-types (TypeScript interfaces instead)
  • Tailwind utility classes for all styling
  • Error handling with try/catch + user-friendly messages
  • API responses follow { data } or { error } pattern

Development Hints

Adding a New Hook Pattern

  1. Patterns are seeded in server/src/db.ts → initDatabase()
  2. Add to the patterns array: [name, template, category, example]
  3. Pattern table has 4 fields: name, template, category, example
  4. Frontend automatically displays new patterns (no changes needed)

Modifying AI Prompts

  • Generation prompt: server/src/services/ai.ts → generateHooks()
  • Analysis prompt: server/src/services/ai.ts → analyzeHook()
  • Both use gpt-4 model with different temperatures (0.9 for generation, 0.7 for analysis)

Adding a New API Endpoint

  1. Add route in server/src/routes/hooks.ts
  2. Use Zod for request validation (see existing generateSchema, analyzeSchema)
  3. Add corresponding method in client/src/api.ts
  4. Update TypeScript interfaces if needed

Database Schema

  • hooks table: id, topic, hook, score, created_at
  • patterns table: id, name, template, category, example
  • Database file: server/data/hooks.db (auto-created)

Frontend Component Pattern

  • Each tab has its own component in client/src/components/
  • Components manage their own state with useState
  • API calls use async/await with loading + error states
  • All components follow same structure: header → form → results