# Porta - Learning Docs

*The gate to LLM providers.*

A Rust library for LLM provider connections with OAuth subscription handling.

## What We Built

Porta allows you to connect to Anthropic's Claude API using your Claude Pro/Max subscription instead of API keys. It handles:

- OAuth PKCE authentication flow
- Token management (storage, refresh)
- Request transformation to match Claude Code's format
- Response transformation

## Docs Index

| Document | Description |
|----------|-------------|
| [Rust Basics](./rust-basics.md) | Rust concepts used in this project |
| [Architecture](./architecture.md) | Project structure and module overview |
| [OAuth Flow](./oauth-flow.md) | How the OAuth authentication works |
| [API Reference](./api-reference.md) | Module and function reference |
| [Troubleshooting](./troubleshooting.md) | Common issues and fixes |

## Quick Start

```bash
# Build the library
cargo build

# Run the CLI
cargo run --bin porta

# Run tests
cargo test
```

## How It Works (TL;DR)

1. **OAuth Flow**: We use Anthropic's OAuth with PKCE to get access tokens from your Claude subscription
2. **Request Transformation**: We modify requests to look like they're from Claude Code (required for OAuth tokens to work)
3. **Token Management**: Access tokens are automatically refreshed when they expire

## Project Status

This is a research/learning project exploring how OAuth subscription access works with LLM providers.

## Why "Porta"?

*Porta* is Latin for "gate" or "door" - fitting for a library that opens the gate to LLM providers. It also follows the Rust tradition of using classical/Latin names (like Cargo, Clippy, etc.).
