# Architecture Documentation

This directory contains comprehensive architecture documentation for the Pinecone Python SDK.

## Overview

The Pinecone Python SDK follows a three-layer architecture with protocol-based interfaces, providing a clear separation between public APIs, type contracts, and implementation details.

## Documentation Files

### 📋 [Overview](./overview.md)
**Start here!** High-level system architecture with diagrams explaining the overall design, component relationships, and key architectural decisions.

**Topics covered:**
- System architecture diagrams
- Three-layer architecture explanation
- Component architecture
- Request flow
- Design decisions and rationale

### 🏗️ [API Structure](./api-structure.md)
Detailed explanation of the three-tier API structure and how different layers interact.

**Topics covered:**
- Public API tier (Layer 1)
- Protocol tier (Layer 2)
- Implementation tier (Layer 3)
- Inter-tier communication
- Module organization
- Import patterns

### 📝 [Specifications](./specifications.md)
Complete protocol specifications including the protocol system and how it works.

**Topics covered:**
- Protocol system overview
- Three-layer protocol model
- Protocol specifications (IPineconeClient, IIndexClient, etc.)
- Protocol implementation requirements
- Protocol verification
- Design patterns

### ✅ [Verification](./verification.md)
Testing strategy, CI pipeline, and quality gates.

**Topics covered:**
- Testing architecture
- Test types (unit, integration, E2E, protocol)
- CI pipeline architecture
- Quality gates
- Local development workflow
- Performance testing

### 🤖 [AI Development Guide](./ai-development.md)
Guide specifically for AI agents working on the SDK.

**Topics covered:**
- Quick start for AI agents
- Standard development workflows
- Common development patterns
- File organization
- Type checking guidance
- Testing patterns
- Error handling
- Quick reference

## Reading Guide

### For New Contributors

1. Read [Overview](./overview.md) to understand the system
2. Read [API Structure](./api-structure.md) to understand organization
3. Read [Specifications](./specifications.md) to understand protocols
4. Reference [AI Development Guide](./ai-development.md) for practical patterns

### For AI Agents

Start with [AI Development Guide](./ai-development.md), which provides:
- Quick start instructions
- Development workflows
- Common patterns and templates
- Quick reference tables
- Links to other relevant docs

### For Understanding Testing

Read [Verification](./verification.md) to understand:
- How tests are organized
- What types of tests to write
- How CI/CD works
- Quality requirements

## Architecture at a Glance

```
pinecone/
├── __init__.py              # Layer 1: Public API (exports only)
├── __interface__/           # Layer 2: Protocols (type contracts)
│   ├── client.py
│   ├── index.py
│   └── data.py
└── _internal/               # Layer 3: Implementation (all logic)
    ├── client.py
    ├── index.py
    ├── data.py
    ├── http/
    ├── models/
    └── utils/
```

## Key Principles

1. **Separation of Concerns** - Clear boundaries between layers
2. **Protocol-Based Design** - Type contracts without inheritance
3. **Type Safety** - Full type annotations and mypy compliance
4. **Explicit Dependencies** - No circular dependencies
5. **Test Coverage** - Comprehensive testing at all layers

## Related Documentation

### Conventions
The [conventions](../conventions/) directory contains detailed coding conventions and guidelines that complement these architecture documents:

- [Architecture Conventions](../conventions/architecture.md) - Layering and module organization rules
- [Type Conventions](../conventions/types.md) - Type system usage
- [Testing Conventions](../conventions/testing.md) - Testing guidelines
- [Error Conventions](../conventions/errors.md) - Error handling patterns
- [Naming Conventions](../conventions/naming.md) - Naming standards
- [And more...](../conventions/README.md)

## Contributing

When making architectural changes:

1. Understand the three-layer architecture
2. Follow protocol-based design
3. Maintain backward compatibility (or version appropriately)
4. Update relevant documentation
5. Ensure all tests pass
6. Update this README if adding new architecture docs

## Questions?

If you have questions about the architecture:

1. Check these architecture documents
2. Check the [conventions documentation](../conventions/)
3. Look at existing code for examples
4. Check the tests for usage patterns
