Implementation Guidance

This document provides high-level direction for implementing features in the Stakeholder Agent System. It serves as a map to help you navigate the codebase and understand where different types of changes belong.

System Overview

For a complete understanding of the system design, including architecture diagrams and quality attributes, see Architecture. For technology details, see Technology Stack.

Where to Make Changes

Frontend Changes

The frontend handles user interface, client-side state, and API communication.

When to modify the frontend:

  • Adding or modifying UI components
  • Implementing client-side validation
  • Managing local state or caching
  • Handling authentication flows

Key patterns:

  • Use functional components with hooks
  • Follow the established component structure
  • Implement proper error boundaries

See Development Workflows - Frontend for coding standards.

Backend Changes

The backend handles AI orchestration, business logic, and data persistence.

When to modify the backend:

  • Adding new API endpoints
  • Implementing AI prompt logic
  • Adding validation or guardrails
  • Managing database operations

Key patterns:

  • Use dependency injection for services
  • Apply async/await for I/O operations
  • Implement proper error handling with custom exceptions

See Development Workflows - Backend for coding standards.

API Changes

When adding or modifying API endpoints:

  1. Define the endpoint in the appropriate controller
  2. Create request/response models with Pydantic
  3. Implement proper validation and error handling
  4. Update the API documentation

See API Documentation for the current endpoint reference and error handling patterns.

Common Implementation Scenarios

Adding a New Feature

  1. Review the architecture - Understand which layers are affected See: Architecture

  2. Create a feature branch - Follow the branching convention See: Development Workflows - Git Workflow

  3. Implement backend logic - Start with the API and service layer

  4. Implement frontend UI - Connect to the backend API

  5. Write tests - Cover both frontend and backend See: Testing Strategy

  6. Submit a pull request - Follow the PR process See: Development Workflows - Pull Request Process

Working with AI Integration

The AI provider is accessed through pydantic AI, which abstracts the underlying provider details:

  • Content guardrails and filtering
  • Provider-specific prompt formatting
  • Token budget management

Key considerations:

  • Use the established Pydantic AI agent interface, not direct provider calls
  • Handle llm-Response-error and context-load-exception gracefully

See Architecture - AI Provider Abstraction for design details.

Working with the Database

All session state persists to Neon Postgres before acknowledgment.

Key patterns:

  • Use connection pooling for performance
  • Implement proper transaction management
  • Follow the established data access patterns

Persisted entities:

  • User accounts and profiles
  • Session metadata and configuration
  • Complete chat history
  • Captured requirements and artifacts

See Testing Strategy - Data Access Layer Tests for testing guidance.

Authentication and Authorization

Authentication is handled by Neon Auth.

Key patterns:

  • All API requests require a valid JWT token
  • Implement tenant-level data isolation

See API Documentation for authentication details.

Quality Requirements

When implementing features, ensure your code meets these quality attributes:

Attribute Target Reference
Response time (unacheived) < 5 sec response time Architecture - Performance
Test coverage 75%+ for services Testing Strategy
Error handling Consistent error format API Documentation - Error Handling
Topic Document
System design and quality attributes Architecture
Technology decisions Technology Stack
Coding standards and workflows Development Workflows
Testing practices Testing Strategy
API reference API Documentation
Common issues Troubleshooting
Contribution process Contributing