Skip to content

Add architecture documentation and Clavius modernization proposal#125

Open
byrcyb wants to merge 2 commits into
masterfrom
docs/architecture-update
Open

Add architecture documentation and Clavius modernization proposal#125
byrcyb wants to merge 2 commits into
masterfrom
docs/architecture-update

Conversation

@byrcyb

@byrcyb byrcyb commented May 5, 2026

Copy link
Copy Markdown
Contributor

Summary

This PR introduces new documentation to support operators and system administrators working with the Callysto infrastructure.

Changes

README.md

Updated to serve as a cleaner entry point:

  • Added a documentation index table linking to all key documents
  • Added an architecture overview diagram
  • Updated OS references from CentOS to Alma Linux 9
  • Added a Retired Components section noting the edX/Tutor decommission
  • Tightened each section to be a concise reference, with depth deferred to ARCHITECTURE.md

ARCHITECTURE.md (new)

Deep-dive reference for operators covering:

  • Full infrastructure topology diagram
  • Deployment workflow sequence (Packer → Terraform → Ansible)
  • Component descriptions: JupyterHub v4, SimpleSAMLphp identity proxy, Sharder, Clavius, SSL certificate management, and Prometheus/Grafana monitoring
  • Authentication flow (end-to-end login sequence)
  • Storage architecture (ZFS + user hash keying)
  • Network and security group summary
  • Environment inventory and how to create new environments
  • Current state notes on the Alma Linux 9 migration and JupyterHub v4 upgrade

CLAVIUS_PROPOSAL.md (new)

Standalone modernization proposal for Clavius:

  • Documents current responsibilities and persistent state
  • Identifies operational risks (CentOS 7 EOL, single point of failure for certs and Terraform state)
  • Presents three options with ASCII architecture diagrams: full CI/CD pipeline, remote state + lightweight ops VM, and in-place rebuild
  • Recommends Option B (remote Terraform state + CI image builds + new Alma Linux 9 ops VM) with a phased migration plan

byrcyb and others added 2 commits May 4, 2026 21:57
- README: modernized for Alma Linux 9 / JupyterHub v4, added component
  table, architecture ASCII diagram, and cross-references to new docs
- ARCHITECTURE.md: new deep-dive covering topology, all components,
  authentication flow, storage design, environments, and future-state
  planning including three options for replacing Clavius with a
  recommendation to migrate Terraform state + Docker builds first

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- ARCHITECTURE.md: remove edX/Tutor as active component, add Retired
  Components section with historical note; extract Clavius replacement
  options into CLAVIUS_PROPOSAL.md with a brief pointer
- CLAVIUS_PROPOSAL.md: new standalone proposal with ASCII topology
  diagrams for all three options (full CI/CD, remote state + ops VM,
  rebuilt Clavius), comparison table, recommendation, and phased
  migration plan
- README.md: add CLAVIUS_PROPOSAL.md to doc table; convert edX section
  to Retired Components

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@byrcyb byrcyb requested review from ianabc and misterhay May 5, 2026 04:02
@byrcyb

byrcyb commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

@ianabc there's a proposal doc for different CLAVIUS modernization options. Something to discuss, refine and figure out which path we want to pursue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant