Welcome to the PredictIQ documentation! This directory contains comprehensive guides, references, and resources for developers, users, and contributors.
docs/
├── README.md # This file
├── API_SPEC.md # API reference and integration guide
├── CONTRACT_ERRORS.md # Smart contract error reference
├── DISTRIBUTED_TRACING.md # Distributed tracing setup and usage
├── api-versioning.md # API versioning policy and guidelines
├── architecture.md # System architecture overview
├── data-flow.md # Data flow documentation
├── deployment.md # Deployment guide
├── secrets.md # Secrets management guide
├── pr/ # Pull request working notes (ephemeral)
└── runbooks/ # Operational runbooks
- Project README - Start here for project overview
- API Specification - API reference and integration guide
- Changelog - Release history and notable changes
- Contributing Guide - Setup, branch naming, commit conventions, and PR process
- API Specification - API reference and integration guide
- Infrastructure README - Infrastructure and deployment overview
- Architecture Overview - System architecture and components
- Data Flow - Data flow through the system
- API Versioning - API versioning policy and guidelines
- Grafana Dashboard Provisioning - Version-controlled dashboard setup
- Distributed Tracing Guide - OpenTelemetry setup and trace propagation
Learn how to optimize gas usage in PredictIQ smart contracts:
- Gas Benchmarks README - Gas benchmark results and methodology
- Infrastructure README - Terraform modules, deployment, and rollback
- Rollback Guide - Emergency rollback procedures
- Deployment Guide - Deployment procedures and configuration
- Secrets Management - Secrets handling and configuration
- Runbooks - Operational runbooks for incident response, including:
- SLO Guide - Service level objectives and error budgets
- API Specification - API reference and integration guide
- Contract Errors - Smart contract error reference
- Database Schema - PostgreSQL schema and migration guide
- Graceful Shutdown - Shutdown behaviour and configuration
- Tracing - API service tracing configuration
- docs/pr/ and frontend/docs/pr/ contain PR-specific working notes (design sketches, review context, temporary investigation notes).
- Purpose: These are ephemeral working notes, not permanent documentation. They exist to support an in-flight or recently merged PR.
- Retention policy: Working notes are retained only while the associated PR is open or recently merged, and are removed once their content has been folded into permanent docs (or is no longer relevant). Do not link to them as stable references.
Developers:
Operators / DevOps:
Users:
Smart Contracts:
Observability:
Integration:
Incident Response:
Found an error or want to improve the documentation?
- Documentation follows the same PR process as code
- Use clear, concise language
- Include code examples where applicable
- Keep documentation up to date with code changes
- Verify all links resolve before submitting
- Use Markdown format
- Include table of contents for long documents
- Add code examples with syntax highlighting
- Link to related documentation
- Keep line length reasonable (80-100 characters)
- Use proper heading hierarchy
When creating or updating documentation:
- Clear and concise writing
- Code examples tested and working
- Links verified
- Spelling and grammar checked
- Follows project style
- Includes table of contents (if long)
- Cross-references added
- Updated in CHANGELOG (if significant)
Have suggestions for improving our documentation?
- Open an issue on GitHub
- Submit a PR with improvements
Last Updated: 2026-04-26
Maintained By: PredictIQ Team