beenvoice/AGENTS.md

beenvoice - AI Assistant Rules

Project Overview

beenvoice is a professional invoicing application built with the T3 stack (Next.js 15, tRPC, Drizzle/LibSQL, NextAuth.js) and shadcn/ui components. This is a business-critical application where reliability, security, and professional user experience are paramount.

Core Development Principles

1. Business-First Approach

• Priority: Reliability and security over flashy features
• User Experience: Professional, clean, and intuitive interface
• Data Integrity: Always validate and sanitize user input
• Error Handling: Graceful degradation with clear user feedback

2. Type Safety & Code Quality

• TypeScript: Use strict TypeScript for all new code
• tRPC: All API calls must go through tRPC for type safety
• Validation: Use Zod schemas for all input validation
• Error Boundaries: Implement proper error handling at all levels

Tech Stack Guidelines

Frontend (Next.js 15 + App Router)

• Use App Router patterns consistently
• Implement proper loading states and error boundaries
• Follow Next.js 15 best practices for performance
• Use React Server Components where appropriate

Backend (tRPC + Drizzle)

• All business logic goes through tRPC routers
• Use Drizzle ORM for all database operations
• Implement proper transactions for multi-table operations
• Follow existing router patterns in src/server/api/routers/

Database (LibSQL/SQLite)

• Use Drizzle migrations for schema changes
• Implement proper indexes for performance
• Follow existing schema patterns
• Use transactions for data consistency

Authentication (NextAuth.js)

• Email/password authentication with bcrypt hashing
• Proper session management
• Protected routes require authentication
• Follow NextAuth.js security best practices

Development Tools

• Use ESLint and Prettier for code formatting
• Use TypeScript for type safety
• Exclusively use bun for development and production. Do not use Node.js or Deno.
• Stay away from starting development servers or running builds unless absolutely necessary.
• Run lints and typechecks when helpful.

Component Architecture

UI Components (shadcn/ui)

• Use shadcn/ui components as the foundation
• Follow existing component patterns
• Use cn() utility for conditional className merging
• Maintain consistent spacing (4px grid system)

Component Organization

• Base UI Components: src/components/ui/ - Pure, portable shadcn/ui components
• Project Components: src/components/ - Project-specific reusable components
• Page Components: src/app/_components/ - Page-specific components

UI Component Rules

What Belongs in src/components/ui/ (Portable)

• Pure shadcn/ui components: button, input, select, dialog, etc.
• Generic layout components: page-layout, card, table
• Basic form components: input, textarea, checkbox, switch
• Navigation components: breadcrumb, navigation-menu
• Feedback components: badge, alert-dialog, toast
• Data display: table, skeleton, progress
• Overlay components: dialog, sheet, popover, dropdown-menu

What Should Move to src/components/ (Project-Specific)

• Business logic components: address-form, status-badge, data-table
• Domain-specific forms: client-form, invoice-form, business-form
• Custom layouts: page-header, dashboard-breadcrumbs
• Feature components: invoice-list, client-list, editable-invoice-items
• Navigation: Sidebar, Navbar, navigation
• Branding: logo, AddressAutocomplete

Immediate Reorganization Needed

Move from src/components/ui/ to src/components/forms/:

• address-form.tsx - Business-specific address handling
• file-upload.tsx - Project-specific file upload logic

Move from src/components/ui/ to src/components/data/:

• data-table.tsx - Enhanced with business logic
• status-badge.tsx - Invoice status specific
• stats-card.tsx - Dashboard-specific statistics

Move from src/components/ui/ to src/components/layout/:

• page-layout.tsx - Project-specific layout patterns
• quick-action-card.tsx - Dashboard-specific actions
• floating-action-bar.tsx - Project-specific floating actions

Keep in src/components/ui/ (Portable):

• button.tsx, input.tsx, select.tsx - Pure shadcn/ui
• dialog.tsx, sheet.tsx, popover.tsx - Generic overlays
• table.tsx, card.tsx, badge.tsx - Base components
• calendar.tsx, date-picker.tsx - Generic date components
• dropdown-menu.tsx, navigation-menu.tsx - Generic navigation
• skeleton.tsx, progress.tsx - Generic loading states

Component Design Principles

• High Reusability: Components should accept props for customization
• Composition over Inheritance: Use children props and render props
• Default Values: Provide sensible defaults for all optional props
• Type Safety: Use TypeScript interfaces for all props
• Accessibility: Include proper ARIA labels and keyboard navigation
• Responsive Design: Mobile-first approach with responsive variants

Component Props Pattern

interface ComponentProps {
  // Required props
  title: string;

  // Optional props with defaults
  variant?: "default" | "success" | "warning" | "error";
  size?: "sm" | "md" | "lg";

  // Styling props
  className?: string;

  // Event handlers
  onClick?: () => void;
  onChange?: (value: string) => void;

  // Content
  children?: React.ReactNode;

  // Accessibility
  "aria-label"?: string;
}

Component Reusability Guidelines

• Configurable Content: Use props for text, labels, and content
• Flexible Styling: Accept className and style props for customization
• Variant System: Use variant props for different visual states
• Size Variants: Provide consistent size options (sm, md, lg, xl)
• Icon Support: Accept icon props for visual customization
• Loading States: Include loading/skeleton variants
• Error States: Handle error states gracefully
• Empty States: Provide empty state components

Component Customization Examples

// Good: Highly customizable component
interface DataTableProps<TData> {
  columns: ColumnDef<TData>[];
  data: TData[];
  title?: string;
  description?: string;
  actions?: React.ReactNode;
  searchKey?: string;
  searchPlaceholder?: string;
  showPagination?: boolean;
  pageSize?: number;
  className?: string;
  emptyState?: React.ReactNode;
  loading?: boolean;
}

// Good: Flexible form component
interface FormFieldProps {
  label: string;
  name: string;
  type?: "text" | "email" | "password" | "number";
  placeholder?: string;
  required?: boolean;
  error?: string;
  className?: string;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  disabled?: boolean;
  onChange?: (value: string) => void;
}

Component File Structure

src/components/
├── ui/                    # Portable base components
│   ├── button.tsx        # Pure shadcn/ui components
│   ├── input.tsx
│   └── ...
├── forms/                # Project-specific forms
│   ├── address-form.tsx
│   ├── client-form.tsx
│   └── invoice-form.tsx
├── layout/               # Layout components
│   ├── page-header.tsx
│   ├── sidebar.tsx
│   └── navbar.tsx
├── data/                 # Data display components
│   ├── data-table.tsx
│   ├── status-badge.tsx
│   └── invoice-list.tsx
├── navigation/           # Navigation components
│   ├── breadcrumbs.tsx
│   └── navigation.tsx
└── branding/             # Brand-specific components
    ├── logo.tsx
    └── address-autocomplete.tsx

Styling Guidelines

• Primary Color: Green (#16a34a) for branding
• Font: Geist font family for professional typography
• Tailwind CSS: Use utility classes consistently
• Responsive Design: Mobile-first approach

Business Logic Patterns

Invoice Management

• Invoice Creation: Multi-step process with validation
• Line Items: Flexible pricing with custom rates
• Status Tracking: draft → sent → paid/overdue
• PDF Generation: Professional invoice formatting

Client Management

• Contact Information: Complete address and contact details
• Search & Filter: Efficient client lookup
• Data Validation: Proper email and phone validation

Business Profile

• Default Business: One default business per user
• Logo Support: Professional branding
• Tax Information: Business tax details

API Development Rules

tRPC Router Patterns

// Follow this pattern for all routers
export const exampleRouter = createTRPCRouter({
  create: protectedProcedure
    .input(z.object({ /* validation schema */ }))
    .mutation(async ({ ctx, input }) => {
      // Business logic here
    }),

  list: protectedProcedure
    .input(z.object({ /* pagination/filtering */ }))
    .query(async ({ ctx, input }) => {
      // Query logic here
    }),
});

Error Handling

• Use toast notifications for user feedback
• Implement proper form validation
• Handle API errors gracefully
• Provide clear error messages

Security

• Always validate user input with Zod
• Check user permissions for all operations
• Sanitize data before database operations
• Use proper authentication checks

Database Schema Rules

Table Structure

• UUID Primary Keys: Use crypto.randomUUID() for all IDs
• Timestamps: Include createdAt and updatedAt fields
• User Relations: All business data linked to users
• Indexes: Proper indexing for performance

Relationships

• Users → Clients: One-to-many
• Users → Businesses: One-to-many
• Users → Invoices: One-to-many
• Clients → Invoices: One-to-many
• Businesses → Invoices: One-to-many
• Invoices → Invoice Items: One-to-many

File Naming Conventions

Components & Pages

• Components: PascalCase (e.g., ClientList.tsx)
• Pages: kebab-case (e.g., new-client.tsx)
• Layouts: layout.tsx (Next.js convention)
• API Routes: route.ts (Next.js convention)

Utilities & Helpers

• Utilities: camelCase (e.g., formatCurrency.ts)
• Constants: UPPER_SNAKE_CASE
• Types: PascalCase (e.g., InvoiceStatus)

Development Workflow

Adding New Features

1. Database Schema: Update schema with migrations
2. tRPC Router: Add procedures with validation
3. UI Components: Create components using shadcn/ui
4. Pages: Implement pages with proper routing
5. Testing: Verify functionality and error handling

Code Quality

• ESLint: Follow existing linting rules
• Prettier: Consistent code formatting
• TypeScript: Strict type checking
• Performance: Optimize database queries and React components

Business Logic Specifics

Invoice Calculations

• Subtotal: Sum of all line items
• Tax: Apply tax rate to subtotal
• Total: Subtotal + tax
• Currency: Handle decimal precision properly

Status Management

• Draft: Initial state, editable
• Sent: Invoice sent to client
• Paid: Payment received
• Overdue: Past due date

Data Validation

• Email: Proper email format validation
• Phone: International phone number support
• Address: Complete address validation
• Currency: Proper decimal handling

Performance Guidelines

Database Optimization

• Use proper indexes for frequently queried fields
• Implement pagination for large datasets
• Use transactions for data consistency
• Optimize query patterns

Frontend Performance

• Use React.memo for expensive components
• Implement proper loading states
• Optimize bundle size
• Use Next.js Image component for images

Caching Strategy

• Use React Query for client-side caching
• Implement proper cache invalidation
• Use Next.js caching where appropriate

Security Considerations

Authentication & Authorization

• All routes require proper authentication
• Check user ownership for all operations
• Implement proper session management
• Use secure password hashing

Data Protection

• Validate all user inputs
• Sanitize data before database operations
• Implement proper error handling
• Use HTTPS in production

Business Data Security

• User data isolation
• Proper access controls
• Audit trails for sensitive operations
• Secure API endpoints

Testing & Quality Assurance

Manual Testing Checklist

• Authentication flows work correctly
• Form validation provides clear feedback
• Responsive design on all screen sizes
• Database operations handle errors gracefully
• PDF generation works correctly
• Navigation and routing function properly

Code Review Guidelines

• Check for proper error handling
• Verify type safety
• Ensure consistent styling
• Review security implications
• Test business logic accuracy

Deployment & Production

Environment Configuration

• Use proper environment variables
• Secure database connections
• Configure NextAuth.js properly
• Set up proper logging

Database Management

• Use migrations for schema changes
• Backup data regularly
• Monitor database performance
• Handle database errors gracefully

Common Patterns & Anti-Patterns

✅ Do's

• Use tRPC for all API calls
• Implement proper loading states
• Use toast notifications for feedback
• Follow existing component patterns
• Validate all user inputs
• Use proper TypeScript types

❌ Don'ts

• Don't use direct fetch calls
• Don't skip input validation
• Don't ignore error handling
• Don't hardcode business logic
• Don't use any types unnecessarily
• Don't skip proper authentication checks

Emergency Procedures

Critical Issues

• Data Loss: Immediate database backup
• Security Breach: Rotate all secrets
• Performance Issues: Database query optimization
• User Complaints: Prioritize user experience fixes

Rollback Strategy

• Keep database migrations reversible
• Maintain version control for all changes
• Test rollback procedures regularly
• Document emergency procedures

Remember

This is a business application where reliability, security, and professional user experience are critical. Every decision should prioritize these values over development convenience or flashy features.

• Don't create demo pages unless absolutely necessary.
• Don't create unnecessary complexity.
• Don't run builds unless absolutely necessary, if you do, kill the dev servers.
• Don't start new dev servers unless asked.
• Don't start drizzle studio- you cannot do anything with it.