feat(docs): developer documentation site

[Depo-dev]

Context

Phase 2 of the PRD requires a developer documentation site. Documentation is not a nice-to-have — it is the primary surface through which new users decide whether to adopt Trident. Without docs, the hosted tier cannot onboard users, and the npm package will have near-zero organic adoption because developers who hit a problem have nowhere to look.

The docs site is also the place where we document our API contract publicly, which creates a healthy forcing function: anything undocumented tends to be poorly designed.

What needs to be built

Tooling recommendation

Mintlify or Fumadocs are the recommended choices:

• Both support MDX (Markdown + JSX components for interactive code examples)
• Both auto-deploy from a docs/ directory in the repo
• Both have free tiers suitable for an open-source project
• Mintlify has a mint.json config file; Fumadocs is Next.js-based (more flexible, more setup)

The choice should be documented in the PR.

Content structure

docs/ at repo root with the following pages:

Getting Started

• Introduction — what Trident is, the problem it solves, the architecture diagram (Stellar RPC → Rust Indexer → Postgres/Redis → Go API → TypeScript SDK)
• Quick Start (SDK) — install @trident-indexer/sdk, get API key, first queryEvents call, working code sample that runs against the hosted testnet API
• Quick Start (Self-hosted) — git clone, cp .env.example .env, docker compose up, first curl against localhost

API Reference (REST)

• GET /v1/events — all query parameters, types, defaults, example request/response, error codes
• GET /v1/events/:id — same treatment
• GET /v1/health — response schema, what each status means
• Authentication — how API keys work, the X-API-Key header, 401 vs 403
• Pagination — how the opaque cursor works, how to iterate all pages, the first and after params
• Rate limiting — what the rate limits are per tier, the Retry-After header, 429 response

API Reference (WebSocket)

• Connecting to GET /ws
• Subscription payload format ({ contractId, topic0 })
• Event message format (same as REST SorobanEvent)
• Reconnection behavior
• Example using the SDK subscribeToContract method
• Example using raw WebSocket (for non-JS clients)

API Reference (GraphQL)

• Full schema listing (auto-generated from the SDL in feat(go-api): GraphQL endpoint with schema mirroring REST #66)
• Example queries: events by contract, events by topic, pagination
• Example subscription
• Link to Playground at /playground

SDK Reference

• TridentClient constructor options
• queryEvents(params) — all params, return type, error handling
• getEventById(params) — same
• subscribeToContract(params) — params, Subscription handle API (unsubscribe(), on('event', ...))
• TridentError — all error codes and what they mean
• Transport selection (REST vs GraphQL)

Self-Hosting Guide

• Prerequisites (Docker, Postgres, Redis)
• Configuration reference (every ENV variable, type, default, and what happens if it's missing)
• Running on Fly.io (link to feat(infra): Fly.io deployment config for hosted tier #69 for the toml files, full deploy walkthrough)
• Upgrading (migration strategy, version compatibility)
• Monitoring (Prometheus metrics from feat(metrics): Prometheus metrics endpoint on the Rust indexer #57/feat(metrics): Prometheus metrics on the Go REST API #58, what each metric means)

Changelog

• Versioned entries for each SDK release and API version

Code examples

Every code example should be a runnable, copy-pasteable snippet. Use the @trident-indexer/sdk package (not raw fetch) for SDK examples. Include TypeScript types explicitly so readers understand the shape of the data.

OpenAPI integration

Once #72 (OpenAPI spec) exists, auto-generate the REST reference pages from the spec rather than hand-writing them. This prevents docs from drifting from the implementation.

Acceptance criteria

• All pages listed above exist with complete, accurate content
• Quick Start (SDK) works end-to-end: a developer following it can make a successful API call in under 5 minutes
• All code examples are valid TypeScript with correct types (run tsc --noEmit against them)
• Docs deploy automatically on push to main (CI step or Mintlify auto-deploy hook)
• No broken internal links (automated link checker in CI)
• Configuration reference is complete — every ENV var in .env.example has a corresponding docs entry
• Changelog entry for Phase 1 (v0.1.0) exists

Dependencies

• feat(go-api): GraphQL endpoint with schema mirroring REST #66 (GraphQL schema — docs reference it)
• feat(go-api): OpenAPI 3.1 spec and generated client types #72 (OpenAPI spec — REST reference can be auto-generated from it)
• All Phase 1 issues (docs describe the shipped functionality)

[Ibk-Bless]

@Ibk-Bless has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello, i can get this done, kindly assign to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ibk-Bless to this issue.