Skip to content

Developer Guide

Extending Potato, driving it through the API, and customizing it.

Architecture Overview

Potato is a Flask-based web application with these core components:

Component File Purpose
Flask app potato/flask_server.py Server startup, data loading, configuration
Routes potato/routes.py HTTP route handlers for annotation workflow
Item state potato/item_state_management.py Singleton managing annotation items and assignment
User state potato/user_state_management.py Singleton tracking user progress and annotations
Config potato/server_utils/config_module.py Configuration loading and validation
Schemas potato/server_utils/schemas/ Annotation type implementations

API Reference

Full REST API documentation for programmatic access:

  • API Reference - All endpoints for authentication, annotation, admin, and data access

Adding New Annotation Types

Schema implementations live in potato/server_utils/schemas/. To add a new type:

  1. Create potato/server_utils/schemas/my_schema.py
  2. Register it in potato/server_utils/schemas/registry.py, declaring every config key the generator reads
  3. Create documentation at docs/annotation-types/<category>/my_schema.md and add it to the mkdocs.yml nav
  4. Add an example project at examples/<category>/my-schema-example/

The registry is the only list of valid types. config_module.py reads it through schema_registry.get_supported_types(), so there is nothing to add there. The Contributing guide has the full checklist, including the tests and the regeneration steps.

For the schema registry API, see the Schema Gallery.

Custom Layouts and UI

Webhooks and Integrations

AI Integration

AI endpoints are in potato/ai/: - ai_endpoint.py - Base endpoint interface - openai_endpoint.py, anthropic_endpoint.py, ollama_endpoint.py, etc.

Development Tools

Testing

pytest tests/unit/ -v        # Fast unit tests
pytest tests/server/ -v      # Server integration tests
pytest tests/selenium/ -v    # Browser tests
pytest --cov=potato --cov-report=html  # Coverage

Contributing