Skip to content

Documentation Structure

Organization

Documentation is organized into the following categories:

docs/
├── README.md                    # Documentation index
├── structure.md                 # This file - documentation structure overview
├── getting-started/             # Getting started guides
│   ├── installation.md         # Installation instructions
│   ├── quick-start.md          # 5-minute quick start guide
│   └── examples.md             # Quick examples
├── guides/                      # User guides (merged usage + user-guide)
│   ├── task-orchestration.md   # Task orchestration guide
│   ├── custom-tasks.md         # Custom tasks creation guide
│   ├── cli.md                  # CLI usage documentation
│   └── api-server.md           # API server setup and usage guide
├── api/                         # API reference documentation
│   ├── python.md               # Python library API reference
│   └── http.md                 # HTTP API reference (A2A Protocol Server)
├── examples/                    # Code examples and tutorials
│   ├── basic_task.md           # Basic task examples and common patterns
│   └── task-tree.md            # Task tree examples with dependencies
├── architecture/                # Architecture and design documents
│   ├── overview.md             # System architecture and design principles
│   ├── directory-structure.md  # Directory structure and naming conventions
│   ├── naming-convention.md    # Naming conventions for extensions
│   ├── extension-registry-design.md  # Extension registry design (Protocol-based)
│   └── configuration.md        # Database table configuration
└── development/                 # Development guides
    ├── setup.md                # Development setup guide for contributors
    ├── extending.md             # Guide for extending the framework
    ├── contributing.md         # Contribution guidelines and process
    └── design/                  # Design documents for specific features
        ├── cli-design.md       # CLI design and implementation
        └── aggregate-results-design.md  # Aggregate results executor design

Root Directory Files

These files remain in the root directory for visibility:

  • README.md - Main user guide and quick start (must be in root for GitHub/PyPI)
  • CHANGELOG.md - Version history and changes (standard location)
  • LICENSE - License file (standard location)

Documentation Categories

Getting Started (docs/getting-started/)

Quick start guides and tutorials for new users.

Purpose: Help users get started quickly with the framework

Contents: - Installation instructions - Quick start guide (5-minute tutorial) - Basic examples

Guides (docs/guides/)

Comprehensive user guides for using aipartnerupflow.

Purpose: Detailed guides for using library features and tools

Contents: - Task orchestration concepts and patterns - Custom task creation and implementation - CLI commands and workflows - API server setup and configuration

Note: This directory merges the previous usage/ (tool usage) and user-guide/ (library features) directories for better organization.

API Reference (docs/api/)

Complete API reference documentation.

Purpose: Detailed API documentation for all interfaces

Contents: - Python API (python.md): Core Python library API reference (TaskManager, ExecutableTask, TaskTreeNode, etc.) - HTTP API (http.md): A2A Protocol Server HTTP API reference

Examples (docs/examples/)

Code examples and tutorials demonstrating common use cases and patterns.

Purpose: Practical examples to help users understand and apply the framework

Contents: - Basic task examples - Task tree examples with dependencies - Common patterns and use cases

Architecture (docs/architecture/)

Detailed technical documentation about system design, architecture decisions, and design patterns.

Purpose: Deep dive into system architecture and design

Contents: - System architecture overview - Directory structure and organization - Naming conventions - Extension registry design - Configuration options

Development (docs/development/)

Guides for developers contributing to the project.

Purpose: Information for contributors and framework extenders

Contents: - Development setup and workflow - Extending the framework (custom executors, extensions, hooks) - Contribution guidelines and process - Design documents for specific features

Subdirectories: - design/: Design documents for specific features

Structure Rationale

This structure follows industry-standard patterns from popular open-source projects:

  • FastAPI: Tutorials → User Guide → Advanced → API Reference
  • Django: Getting Started → Topics → How-to → API Reference
  • LangChain: Getting Started → Modules → Use Cases → API

Key improvements from previous structure: 1. Reduced from 11 top-level directories to 6 2. Merged related content (usage/ + user-guide/ → guides/) 3. Unified API documentation (Python + HTTP → api/) 4. Consolidated configuration into architecture 5. Organized development docs with subdirectories 6. Removed empty directories

Typical user journey through the documentation:

  1. New Users: getting-started/ → guides/ → examples/
  2. API Users: api/ → examples/
  3. Framework Extenders: guides/custom-tasks.md → development/extending.md → architecture/
  4. Contributors: development/setup.md → development/contributing.md → architecture/