veridian/AGENTS.md

AGENTS.md

This file contains guidelines and commands for agentic coding agents working in the Veridian repository.

Project Overview

Veridian is a Nuxt 4 application built with TypeScript, using PostgreSQL with Drizzle ORM, better-auth for authentication, and UnoCSS for styling. The app is an agnetic chat platform that is meant to provide a well rounded experience for interacting with LLMs as well as providing a way to manage agents and provide helpful tools like RAG (retrieval augmented generation) and web scraping/search.

You should be connected to the Nuxt docs MCP server, if you need to reference the documentation or are unsure on how to implement something, consult the docs.

Core Commands

As an agentic agent, never run the development server yourself. Instead, once you have completed your task, end generation and inform me that you are done and request a review of your changes. You are allowed to use database commands.

Database Commands

• tsx db/migrate.ts - Run database migrations
• bun x @better-auth/cli@latest generate --output db/auth/auth.schema.ts - Generate authentication schema based on lib/auth.ts
• bun x drizzle-kit generate - Generate migration files
• bun x drizzle-kit push - Push schema changes to database
• bun x drizzle-kit studio - Open Drizzle Studio for database inspection

Tech Stack & Dependencies

• Framework: Nuxt 4 (SSR enabled)
• Language: TypeScript with strict configuration
• Database: PostgreSQL with Drizzle ORM
• Auth: better-auth with email/password and social providers
• Styling: UnoCSS with presetMini
• Icons: @nuxt/icon with Iconify, use Myna UI Icons

Code Style Guidelines

Follow the LLVM golden rule: If you are extending, enhancing, or bug fixing already implemented code, use the style that is already being used so that the source is uniform and easy to follow.

• Always end lines with a semicolon regardless of surrounding code
• Use 4 spaces for indentation
• Use consistent naming conventions for variables, functions, and constants
• Always use strict equality checks (=== and !==) instead of loose equality checks (== and !=)
• Prefer using explicity equality checks over truthy/falsy checks e.g., prefer if (value !== null) instead of if (value)
• Always check existing code patterns before implementing new features
• Follow existing component and composable structures
• Use proper TypeScript types for all function parameters and returns
• Implement proper cleanup in composables (e.g., useClickOutside)
• Prefer reactive state management over direct DOM manipulation
• Keep components focused and single-purpose
• Use semantic HTML elements where appropriate

General Structure

• Use Nuxt's app directory structure (app/, server/, lib/)
• Auth configuration in lib/auth.ts
• Server API routes go in server/api/
• Composables go in app/composables/
• Database schema in db/schema.ts
• Database migrations in db/migrations/

TypeScript Guidelines

• Use strict TypeScript with no implicit any
• Export types and interfaces explicitly
• Use computed() and ref() from Vue 3 reactivity system
• Type API responses and database models

Vue Components

• Never use self-closing tags, excluding images, br, hr, and input
• Use <script setup lang="ts"> syntax
• Strongly prefer composition API over options API
• Prefer composables for shared state management
• Maintain consistent 4-space indentation
• Use PascalCase for component file names

CSS/Styling

• Use UnoCSS utility classes exclusively
• Never use margin for spacing, always prefer flexbox or grid
• Prefer inline utility classes over custom CSS
• Use semantic color variables: --color-base, --color-neutral, --color-accent, --color-subtle If you need to add new color variables, they are located in app/assets/css/base.css, along with a general CSS reset.
• Apply consistent spacing and layout patterns
• Use responsive prefixes only when necessary

Imports

• Order imports: Vue/Nuxt imports first, then local files, then dependencies
• ~/ is an alias for app/ and ~~/ is an alias for the root of the project
• Avoid wildcard imports
• Keep imports sorted alphabetically within groups

Naming Conventions

• Page: camelCase
• Composables: camelCase
• Components: PascalCase when referenced in templates
• Functions/Variables: camelCase
• Constants: UPPER_SNAKE_CASE for environment variables only
• Database tables: snake_case
• API routes: kebab-case path segments

Database Patterns

• Use Drizzle ORM with PostgreSQL
• Export all schemas from db/schema.ts
• Use environment variables for database credentials
• db/auth/auth.schema.ts is a generated file, do not touch it. If you need to change the authentication schema, edit lib/auth.ts and run the generation script.

Error Handling

• Use proper TypeScript error types
• Implement try-catch blocks for database operations
• Provide user-friendly error messages in API responses
• Log errors appropriately without exposing sensitive data

Performance Guidelines

• Leverage Nuxt's auto-imports and code splitting
• Use useState() for shared state across components
• Implement proper loading states with async operations
• Optimize database queries and use indexes where needed

Authentication Implementation

The app uses better-auth with:

• Email/password authentication (configurable via env vars)
• Drizzle adapter for PostgreSQL
• Session management through cookies
• Auth plugins in app/plugins/ for client/server initialization
• Global auth middleware in app/middleware/auth.global.ts

All users must be signed in to view pages aside from authentication pages. (located in app/pages/auth/), you do not need to check if session or user objects are null or undefined, use the non-null assertion operator (!) where necessary. In API routes, you can use protectRoute to guarantee that the user must be authenticated.

File Organization

|-- app/                   # Application code
│   |-- components/        # Vue components
│   |-- composables/       # Reuseable composition functions
│   |-- layouts/           # Layout components
│   |-- middleware/        # Route middleware
│   |-- pages/             # File-based routing
│   \-- plugins/           # Vue/Nuxt plugins
|-- server/                # Server-side code
│   \-- api/               # API routes
|-- db/                    # Database related files
│   |-- schema.ts          # Database schema
│   |-- migrate.ts         # Migration runner
│   \-- migrations/        # Migration files
\-- lib/                   # Shared utilities

Testing

Currently no test framework is configured, and tests are not currently a requirement.

Environment Variables

Key environment variables:

• DATABASE_URL - PostgreSQL connection string
• BETTER_AUTH_SECRET - Authentication secret
• DISABLE_LOCAL_AUTH - Disable email/password auth
• DISABLE_SIGNUP - Disable user registration

Common Patterns

Composables Pattern

export const useFeature = () => {
  const state = useState<Type>('feature:state', () => defaultValue)
  const computed = computed(() => /* logic */)

  const actions = {
    // methods
  }

  return { state, computed, ...actions }
}

API Route Pattern

API routes are defined in server/api/ and are exported as a single object.

File names contain information about the route, e.g. user.get.ts specifies a GET route to /user. This applies for all HTTP methods.

// an example GET route to /user
export default defineEventHandler(async (event) => {
  try {
    // implementation
    return { success: true, data: result };
  } catch (error) {
    throw createError({
      statusCode: 500,
      statusMessage: "Error description",
    });
  }
});

import { users } from "~~/db/schema";

// an example POST route to /user
export default defineEventHandler(async (event) => {
  const body = await readBody(event);

  const { email, name, password } = body;

  const [user] = await db
    .insert(users)
    .values({ email, name, password })
    .returning();

  return user;
});