creddit internal documentation

Engineering documentation for creddit, the institutional analytics terminal for yield-bearing collateral in onchain lending protocols (creddit.xyz). This is internal, for the team: it should let a new member understand how the app works end to end, where the data comes from, how it is deployed, and how we operate it. It is not user-facing product documentation.

Read Architecture first; it links out to everything else.

Start here

• Architecture — what creddit is, the tech stack, the read/write paths, the routes, and a full repo map.

Features

• Portfolio (read-only) — the signed-in position monitor: coverage, the yield-only USD/ETH/BTC books plus the cross-asset view for financed positions, the two valuation marks, and the workstream status.

Data

• Database & schema — the onchain_credit Postgres schema, every table and what it holds.
• Data pipeline & refreshers — what data is updated, how, and at what frequency (the cron-scheduled refreshers and the upstream sources).
• Metrics: how & why — every metric the app shows, its exact formula, and the reasoning behind it (incl. the canonical APY convention and oracle transparency).

Operations

• Deployment & server ops — the develop-on-staging / promote-to-prod flow (with a step-by-step runbook), versioned releases, server topology, and the operational runbook.
• Operational processes — listing a new carry trade end to end, and staying in sync with asset-profile and registry changes.
• External dependencies — every external service (RPCs, DefiLlama, Dune, Morpho/Euler, NY Fed SOFR, Cloudflare) and the env vars they need.

Keeping these docs current

Any pull request merged to main (production) must include the relevant documentation updates. If you change a schema, a refresher or its cadence, a metric, the deploy/server setup, an external dependency, or a listing/sync process, update the matching page here in the same PR. Treat the docs as part of the change, not an afterthought.