Skip to main content

Design Documents (Planned)

This section outlines the planned formal design documents for the Gamuda Technology Jira Tracker. These will provide a single source of truth for architecture and operations.

1. Data Design Document​

Status: Planned
Goal: Describe data models, storage, and access patterns in one place.

Planned contents​

  • Data model overview — Entities (projects, people, worklogs, reports, work arrangements) and relationships
  • Firestore collections — Canonical list with purpose, key structure, and indexes
  • Schema evolution — How we add/change fields and collections; migration approach
  • Security rules — How Firestore rules map to RBAC and data isolation
  • Sync and consistency — Deterministic sync, offline behavior, conflict handling
  • Reference — Links to types in apps/web/src/types/ and Data overview / Database structure

Suggested improvements to adopt​

  • Document a single canonical schema (e.g. generated or hand-maintained) and keep code types in sync
  • Add data dictionary (field-level description, types, constraints)
  • Define retention and archival policy for old reports and worklogs
  • Document backup and restore procedures for Firestore

2. Infrastructure Design Document​

Status: Planned
Goal: Describe how the system is hosted and wired on GCP.

Planned contents​

  • High-level diagram — GCP project(s), Cloud Run, Firestore, Firebase Hosting, Cloud Build
  • Networking — Regions, VPC (if any), ingress/egress
  • Identity and secrets — Service accounts, Secret Manager usage, Firebase project linkage
  • Environments — Dev vs prod (and any staging); how PROJECT_ID and Firebase project are chosen
  • Terraform layout — What is managed in infrastructure/terraform and what is not
  • Reference — Deployment Flow, Deployment Guide, Terraform README

Suggested improvements to adopt​

  • Environment parity — Clear dev/staging/prod checklist (APIs, quotas, feature flags)
  • Cost and quotas — Document expected usage and set budget alerts
  • Disaster recovery — RTO/RPO and steps to restore from backup or rebuild
  • Infrastructure as Code — Extend Terraform coverage for any remaining manual resources

3. DevOps & Operations Design Document​

Status: Planned
Goal: Describe how we build, deploy, and operate the application.

Planned contents​

  • CI/CD — Triggers (e.g. GitHub Actions), build (Cloud Build), deploy (Cloud Run), and rollback
  • Deployment pipeline — Step-by-step from commit to live (align with deploy-to-gcp.sh and Deployment Flow)
  • Secrets and config — Where they live (env, Secret Manager), how they are injected at build and runtime
  • Monitoring and alerting — Logs, metrics, dashboards, and who is notified
  • Runbooks — Common operations: deploy, rollback, clear caches, re-run sync, troubleshoot saves
  • Reference — Deployment flow, Production saves troubleshooting

Suggested improvements to adopt​

  • Staged rollouts — Canary or percentage-based traffic for Cloud Run
  • Health and readiness — Explicit health endpoints and use in load balancer
  • Structured logging — Consistent fields (e.g. trace id, user id) for debugging
  • Incident process — Ownership, severity, and post-incident review template

How to use these when ready​

Once each design document is written:

  1. Store it in the Docusaurus docs (e.g. under Design or under Operations) and link it from the sidebar.
  2. Keep a short Design Documents index page (this page) that links to each and states their status.
  3. Replace or deprecate overlapping content in other docs by linking to the design doc as the source of truth.
  4. Review and update design docs as part of major changes (new environment, new data model, new pipeline).