# architecture
## tangled platform overview
tangled is a git collaboration platform built on the AT Protocol. it consists of:
### components
- **appview** (tangled.org): web interface using traditional HTTP routes
- handles OAuth authentication for browser users
- serves HTML/CSS/JS for the UI
- proxies git operations to knots
- does NOT expose XRPC endpoints
- **knots** (e.g., knot1.tangled.sh): git hosting servers
- expose XRPC endpoints for git operations
- host actual git repositories
- handle git-upload-pack, git-receive-pack, etc.
- **PDS** (Personal Data Server): AT Protocol user data storage
- stores user's atproto records
- repos stored in `sh.tangled.repo` collection
- each repo record contains: name, knot, description, etc.
### data flow
1. user creates repo on tangled.org
2. appview writes repo record to user's PDS (`sh.tangled.repo` collection)
3. repo record includes `knot` field indicating which knot hosts it
4. git operations routed through appview to the appropriate knot
## MCP server implementation
### resolution flow
when a client calls `list_repo_branches("@owner/repo")`:
1. **normalize input**: strip @ if present (`@owner` → `owner`)
2. **resolve handle to DID**:
- if already DID format: use as-is
- otherwise: call `com.atproto.identity.resolveHandle`
- result: `did:plc:...`
3. **query repo collection**:
- call `com.atproto.repo.listRecords` on owner's PDS
- collection: `sh.tangled.repo` (NOT `sh.tangled.repo.repo`)
- find record where `name` matches repo name
4. **extract knot**:
- get `knot` field from repo record
- example: `knot1.tangled.sh`
5. **call knot XRPC**:
- construct URL: `https://{knot}/xrpc/sh.tangled.repo.branches`
- params: `{"repo": "{did}/{repo_name}", "limit": N}`
- auth: service token from `com.atproto.server.getServiceAuth`
### authentication
uses AT Protocol service auth:
1. authenticate to user's PDS with handle/password
2. call `com.atproto.server.getServiceAuth` with `aud: did:web:tangled.org`
3. receive service token (60 second expiration)
4. use token in `Authorization: Bearer {token}` header for XRPC calls
### key implementation details
- **collection name**: `sh.tangled.repo`
- **knot resolution**: dynamic based on repo record, not hardcoded
- **handle formats**: both `owner/repo` and `@owner/repo` accepted
- **private implementation**: resolution logic in `_tangled/` package
- **public API**: clean tool interface in `server.py`
### error handling
- invalid format: `ValueError` with clear message
- handle not found: `ValueError` from identity resolution
- repo not found: `ValueError` after querying collection
- XRPC errors: raised from httpx with status code
