// TECHNICAL DEEP-DIVE
How OCXP Works
A technical overview of the transport layer, provider abstraction, and federation system that powers OCXP.
// LAYER 1
Transport Abstraction
All providers implement the same interface, regardless of the underlying storage.
OCXPTransport.ts
interface OCXPTransport {
// Discovery
list(path: string): Promise<OCXPEntry[]>
exists(path: string): Promise<boolean>
// Read operations
read(path: string): Promise<Buffer>
readText(path: string): Promise<string>
readJSON<T>(path: string): Promise<T>
// Write operations (optional)
write?(path: string, content: Buffer): Promise<void>
delete?(path: string): Promise<void>
// Metadata
getInfo(path: string): Promise<OCXPFileInfo>
}URI Scheme Routing
s3://->S3 Provider
github://->GitHub Provider
file://->Local Provider
https://->HTTP Provider
// PROVIDERS
Built-in Providers
OCXP ships with providers for common storage backends. All speak the same protocol.
providers.ts
// S3 Provider
const s3Provider = new S3OCXPAdapter({
bucket: 'my-context-bucket',
region: 'us-east-1',
});
// GitHub Provider
const githubProvider = new GitHubOCXPAdapter({
repo: 'my-org/context-repo',
branch: 'main',
token: process.env.GITHUB_TOKEN,
});
// Local Provider
const localProvider = new LocalOCXPAdapter({
root: './context',
});
// All implement the same interface!| Provider | URI Format | Capabilities |
|---|---|---|
| S3 | s3://bucket/path | read, write, delete, list, sync |
| GitHub | github://owner/repo | read, list |
| Local | file:///path | read, write, delete, list, sync |
| HTTP | https://api.example.com | read, list |
| Google Drive | gdrive://folder-id | read, list, sync |
// OPERATIONS
Reading Context
The client provides intuitive methods for listing and reading context.
reading.ts
import { OCXPClient } from '@ocxp/client';
const client = new OCXPClient('https://api.ocxp.dev');
// List available missions
const missions = await client.list('missions/');
// Returns: OCXPEntry[]
// Read a specific file
const phases = await client.read('missions/my-project/PHASES.md');
// Returns: { content: string, type: 'markdown', info: {...} }
// Read JSON with type safety
const metadata = await client.readJSON<MissionMetadata>(
'missions/my-project/metadata.json'
);
// Returns: MissionMetadata object// FEDERATION
Multi-Source Queries
Combine results from multiple providers with intelligent merging.
federation.ts
import { OCXPFederation, OCXPClient, LocalOCXPAdapter } from '@ocxp/client';
// Create federation with multiple sources
const federation = new OCXPFederation({
mergeStrategy: 'team_first',
tolerateFailures: true,
});
// Register team server
federation.registerProvider('team',
new OCXPClient('https://team-api.company.com')
);
// Register local development
federation.registerProvider('local',
new LocalOCXPAdapter({ root: './my-context' })
);
// Query across all sources
const allMissions = await federation.listMissions();
// Returns merged results with source attribution
// Load from specific source
const mission = await federation.loadMission('my-project', 'team');*----*|
||
|*----*
Federation Flow
1. Query received
│
v
2. Route to all registered providers
├── team: GET /ocxp/missions/list
└── local: scan ./my-context/missions/
│
v
3. Collect results (parallel)
├── team: [mission-a, mission-b]
└── local: [mission-c, mission-a] <- duplicate!
│
v
4. Apply merge strategy (team_first)
- mission-a: team version wins
- mission-b: from team
- mission-c: from local
│
v
5. Return merged results with source attribution
[
{ id: 'mission-a', source: 'team' },
{ id: 'mission-b', source: 'team' },
{ id: 'mission-c', source: 'local' }
]
// ERRORS
Error Handling
Standard error codes mapped to HTTP status for consistent handling.
| Code | Name | HTTP | Retryable |
|---|---|---|---|
| 1001 | NOT_FOUND | 404 | No |
| 1002 | PERMISSION_DENIED | 403 | No |
| 1003 | INVALID_PATH | 400 | No |
| 1004 | PROVIDER_ERROR | 500 | Yes |
| 1005 | AUTH_REQUIRED | 401 | No |
| 1006 | RATE_LIMITED | 429 | Yes |