docs: add architecture diagram, data-flow guide, deployment guide, and OpenAPI CI drift check#1009
Merged
hman38705 merged 4 commits intoJun 30, 2026
Conversation
…utions-plug#1003) Adds docs/architecture.md with a Mermaid C4 level-1 system context diagram and a C4 level-2 container diagram showing all services (API, TTS, frontend), databases (PostgreSQL, Redis), external dependencies (Stellar RPC, SendGrid), and network boundaries (VPC public/private subnets). Includes an architecture-review checklist item for PRs that touch these boundaries. Closes solutions-plug#1003 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…utions-plug#1004) Adds docs/data-flow.md documenting the full lifecycle of every major data type (email addresses, subscription status, audit events, market data, on-chain bets, email tracking, analytics events, and transient Redis data). Each entry covers collection point, storage location, retention period, deletion mechanism, and access control. Includes a Mermaid data-flow diagram, a GDPR data-subject-rights implementation map, an access-control summary table, and outstanding action items for future compliance work. Closes solutions-plug#1004 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…lutions-plug#1005) Adds utoipa 4 as a dependency and wires up automatic OpenAPI spec generation from Axum route annotations: - services/api/src/handlers.rs: all 26 public handler functions annotated with #[utoipa::path(...)]; request/response types derive ToSchema / IntoParams - services/api/src/pagination.rs: adds the missing PaginationQuery struct (with limit() / cursor() helpers) that handlers.rs already imported; derives IntoParams for utoipa - services/api/src/openapi_spec.rs: new module housing the #[derive(OpenApi)] struct that lists every annotated path and component schema - services/api/src/bin/generate_openapi.rs: new binary that serialises ApiDoc to YAML on stdout; run with: cd services/api && cargo run --bin generate-openapi > openapi.yaml - .github/workflows/test.yml: new openapi-drift-check job builds the binary, generates the spec, and fails CI if the annotated path set diverges from the committed openapi.yaml; added to all-tests-passed gate - .github/pull_request_template.md: checklist items remind contributors to regenerate the spec and update docs/architecture.md when relevant Closes solutions-plug#1005 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds docs/deployment.md covering all steps a new team member needs to deploy PredictIQ from scratch: - Prerequisites (AWS CLI, Terraform, Docker, Rust, psql, gh) - First-time infrastructure provisioning via Terraform bootstrap script, plan, apply, and Secrets Manager setup - Environment variable reference table (required + optional/tuning) derived from config.rs - Normal deployment workflow: merge → GHCR image build → ECS rolling update → health validation - Database migration process: apply, check status, write new migrations (with rollback script requirement) - Rollback procedures for application, database, and infrastructure, with timeline targets - Validation checklist with six curl / AWS CLI commands to run after every production deployment Closes solutions-plug#1002 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
@Mystery-CLI Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
hman38705
added a commit
that referenced
this pull request
Jun 30, 2026
…oyment guide, and OpenAPI CI drift check
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #1002, closes #1003, closes #1004, closes #1005
Four documentation and tooling gaps addressed in a single PR:
No system architecture diagram — relationships between services are undocumented #1003 —
docs/architecture.md: C4 Level 1 (system context) and C4 Level 2 (container) diagrams in Mermaid showing all services (API, TTS, frontend), databases (PostgreSQL, Redis), external dependencies (Stellar RPC, SendGrid), network boundaries (VPC public/private subnets), and a network-boundary table. Includes a per-PR architecture-review checklist.No data flow diagram — data lifecycle through the system is undocumented #1004 —
docs/data-flow.md: Full lifecycle document for every major data type (email addresses, subscription status, audit events, market data, on-chain bets, email tracking, analytics events, and Redis transient data). Each type documents collection point, storage location, retention period, deletion mechanism, and access control. Includes a Mermaid data-flow diagram, a GDPR data-subject-rights implementation map, and an access-control summary table.API spec (openapi.yaml) drift from implementation not caught automatically in CI #1005 — utoipa integration + CI drift check:
utoipa = "4"added toservices/api/Cargo.tomlPaginationQuerystruct added topagination.rs(was referenced inhandlers.rsbut missing)#[utoipa::path(...)]; request/response types deriveToSchema/IntoParamsservices/api/src/openapi_spec.rs:#[derive(OpenApi)]listing all annotated pathsservices/api/src/bin/generate_openapi.rs: binary that outputs the spec as YAML (cargo run --bin generate-openapi > openapi.yaml).github/workflows/test.yml: newopenapi-drift-checkjob builds the binary, generates the spec, and fails CI if the annotated path set diverges from the committedopenapi.yaml; added toall-tests-passedgate.github/pull_request_template.md: checklist items for spec regeneration and architecture diagram updatesNo production deployment guide — deployment process is undocumented #1002 —
docs/deployment.md: Step-by-step production deployment guide covering prerequisites, first-time Terraform provisioning (bootstrap → plan → apply → Secrets Manager), all environment variables (required + optional, sourced fromconfig.rs), normal deployment workflow (merge → GHCR image → ECS rolling update), database migration process, rollback procedures (application, DB migration, infrastructure) with timeline targets, and a six-step validation checklist.Test plan
docs/architecture.mdanddocs/data-flow.mdpreview)cargo build --bin generate-openapisucceeds inservices/api/cargo run --bin generate-openapioutputs valid YAMLopenapi-drift-checkCI job passes (path sets matchopenapi.yaml)🤖 Generated with Claude Code