Codebase Development Guide

This document outlines the patterns and conventions to follow when working with this codebase.

Schema Patterns

Schema Definitions

1. All schemas must be defined in src/schemas/ directory
2. Each schema should have:
3. A TypeScript interface
4. Added to SchemaType enum in SchemaTypes.ts
5. Schema files should:
6. Be named <SchemaName>Response.ts for response types
7. Export both interface and schema (if needed)
8. Include JSDoc comments for all properties

Example schema file:

export interface ExampleResponse {
    /**
     * Description of property
     */
    property: string;
}

Schema Usage

1. Always use getGeneratedSchema() to get schema definitions
2. Use StructuredOutputPrompt for LLM requests
3. Schema types should match the response interface

Executor Patterns

Executor Structure

1. Must implement StepExecutor interface
2. Use @StepExecutorDecorator for registration
3. Follow dependency injection pattern in constructor
4. Use modelHelpers.generate() for LLM interactions

Common Patterns

1. URL handling:
2. Use scrapeHelper.normalizeUrl()
3. Track visited URLs with Set
4. Validate URLs with new URL()
5. Artifact management:
6. Use artifactManager.saveArtifact()
7. Include metadata with:
   • URL
   • Task/step
   • Project ID
   • Token usage
8. Error handling:
9. Use Logger.error()
10. Return meaningful error responses
11. Catch and handle specific errors

Testing Guidelines

1. Tests should:
2. Mock external dependencies
3. Test error cases
4. Verify schema usage
5. Check token tracking
6. Use Jest for testing
7. Follow Arrange-Act-Assert pattern

Documentation Standards

1. Add JSDoc comments for:
2. All public methods
3. Interface properties
4. Complex logic
5. Use markdown format for documentation
6. Keep documentation in /docs folder
7. Update documentation with changes

Code Style

1. Follow TypeScript best practices
2. Use async/await for promises
3. Prefer functional patterns over imperative
4. Keep methods focused and small
5. Use descriptive variable names
6. Follow existing code style and patterns

This guide documents the key patterns and conventions used in the codebase. Let me know if you'd like me to add any additional sections or details!