# tarwaaa/zero-gravity-cs architecture

> Architecture diagram of the GitHub repository tarwaaa/zero-gravity-cs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tarwaaa/zero-gravity-cs
- Repository: https://github.com/tarwaaa/zero-gravity-cs

## Overview

#### Purpose and runtime

This repository is a single-page Streamlit prototype for teacher onboarding into Zero Gravity. It prioritises demonstrating a scripted student tutor experience before class confirmation and optional assignment publication. The executable entry point is `app.py`; Streamlit presentation defaults are in `.streamlit/config.toml`. Dependencies and test runtime are defined by `requirements.txt`.

#### Application shell and stateful navigation

`app.py` owns the full UI, workflow routing, local styling, and session-state lifecycle. Streamlit session state acts as the only persistence boundary: it stores current journey stage, selected class, assignment edits, and published/completed status during a browser session. Restart/reset returns the prototype to its initial state; there is no backend, authentication, or durable store.

#### Tutor-preview stage

The first activation stage in `app.py` presents a fixed Year 9 Mathematics tutor interaction. Teacher responses are constrained to scripted choices and produce predetermined replies. This is a product-value demonstration boundary: no model, student account, content service, or input interpretation is invoked.

#### Class-confirmation stage

The next stage exposes a static, mocked MIS-synchronised list of three existing classes within `app.py`. The selected class is retained in session state and becomes context for later setup and assignment views. No MIS API, school data source, permission check, or student roster is connected.

#### Next-action decision boundary

After class selection, the flow branches in `app.py`: teachers can finish setup immediately or continue to a recommended starter-assignment route. This is the central control-flow decision. Finishing setup preserves the truthful empty-product state rather than implying existing student activity; assignment setup remains available as the recommended continuation.

#### Assignment authoring and publication

The optional route in `app.py` displays a prefilled starter assignment. Teachers can edit title, question count, and due date; difficulty remains fixed. Duration is derived locally from question count using the prototype’s rounding rule, rather than a service or analytics model. Publishing changes only Streamlit session state and leads to an assignment-success view; it does not create a remote assignment or notify students.

#### Status, insights, and validation boundaries

Success and activity views in `app.py` explicitly distinguish zero real student starts from illustrative future insights. The prototype therefore avoids representing simulated information as operational analytics. Behavior is protected through Streamlit AppTest/pytest coverage in `tests/test_app.py`, including route transitions, retained state, validation, publication, restart, and duration calculation.

Main entry points: [`app.py`](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py) (Starter assignment setup), [`tests/test_app.py`](https://github.com/tarwaaa/zero-gravity-cs/blob/main/tests/test_app.py) (AppTest coverage), [`.streamlit/config.toml`](https://github.com/tarwaaa/zero-gravity-cs/blob/main/.streamlit/config.toml) (Streamlit defaults), [`requirements.txt`](https://github.com/tarwaaa/zero-gravity-cs/blob/main/requirements.txt) (Dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Streamlit prototype"]
  node_streamlit{{"Streamlit runtime<br/>UI runtime<br/>[app.py]"}}
  node_app_shell["App shell and routing<br/>workflow controller<br/>[app.py]"]
  node_session_state[("Session state<br/>ephemeral state<br/>[app.py]")]
  node_duration_rule["Duration calculation<br/>local rule<br/>[app.py]"]
  node_app_tests["AppTest coverage<br/>pytest validation<br/>[test_app.py]"]
  node_streamlit_config["Streamlit defaults<br/>runtime configuration<br/>[config.toml]"]
  node_requirements["Dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

subgraph group_flow["Onboarding flow"]
  node_tutor_preview["Tutor preview<br/>scripted interaction<br/>[app.py]"]
  node_class_confirmation["Class confirmation<br/>mock class selector<br/>[app.py]"]
  node_next_action{{"Next-action decision<br/>flow branch<br/>[app.py]"}}
  node_empty_status["Empty product status<br/>completion view<br/>[app.py]"]
  node_assignment_authoring["Starter assignment setup<br/>authoring form<br/>[app.py]"]
  node_publication["Publish assignment<br/>state transition<br/>[app.py]"]
  node_success_insights["Success and insights<br/>status view<br/>[app.py]"]
end

node_streamlit -->|"runs"| node_app_shell
node_streamlit_config -->|"configures"| node_streamlit
node_requirements -.->|"provides runtime"| node_streamlit
node_app_shell -->|"reads and writes"| node_session_state
node_app_shell -->|"starts at"| node_tutor_preview
node_tutor_preview -->|"continues to"| node_class_confirmation
node_class_confirmation -->|"stores selected class"| node_session_state
node_class_confirmation -->|"confirms class"| node_next_action
node_next_action -->|"finish setup"| node_empty_status
node_next_action -->|"recommended route"| node_assignment_authoring
node_assignment_authoring -->|"uses question count"| node_duration_rule
node_assignment_authoring -->|"stores edits"| node_session_state
node_assignment_authoring -->|"publishes"| node_publication
node_publication -->|"sets published status"| node_session_state
node_publication -->|"shows success"| node_success_insights
node_app_tests -.->|"validates behavior"| node_app_shell

click node_streamlit "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_app_shell "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_session_state "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_tutor_preview "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_class_confirmation "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_next_action "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_empty_status "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_assignment_authoring "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_duration_rule "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_publication "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_success_insights "https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py"
click node_app_tests "https://github.com/tarwaaa/zero-gravity-cs/blob/main/tests/test_app.py"
click node_streamlit_config "https://github.com/tarwaaa/zero-gravity-cs/blob/main/.streamlit/config.toml"
click node_requirements "https://github.com/tarwaaa/zero-gravity-cs/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_app_shell,node_session_state,node_duration_rule,node_app_tests,node_streamlit_config,node_requirements toneBlue
class node_tutor_preview,node_class_confirmation,node_next_action,node_empty_status,node_assignment_authoring,node_publication,node_success_insights toneAmber
```

## Components

### Streamlit prototype

Single-process teacher onboarding experience.

- [Streamlit runtime](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): UI runtime · `app.py`
- [App shell and routing](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): workflow controller · Owns presentation, routing, styling, and lifecycle. · `app.py`
- [Session state](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): ephemeral state · Only persistence boundary; resets with the browser session. · `app.py`
- [Duration calculation](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): local rule · Derives duration from question count using prototype rounding. · `app.py`
- [AppTest coverage](https://github.com/tarwaaa/zero-gravity-cs/blob/main/tests/test_app.py): pytest validation · Covers routes, state retention, validation, publication, reset, and duration. · `tests/test_app.py`
- [Streamlit defaults](https://github.com/tarwaaa/zero-gravity-cs/blob/main/.streamlit/config.toml): runtime configuration · `.streamlit/config.toml`
- [Dependencies](https://github.com/tarwaaa/zero-gravity-cs/blob/main/requirements.txt): dependency manifest · `requirements.txt`

### Onboarding flow

State-driven stages rendered by app.py.

- [Tutor preview](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): scripted interaction · Fixed Year 9 Maths demonstration with predetermined replies. · `app.py`
- [Class confirmation](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): mock class selector · Shows three static MIS-like classes. · `app.py`
- [Next-action decision](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): flow branch · Choose finish setup or starter-assignment setup. · `app.py`
- [Empty product status](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): completion view · Truthfully shows no student activity after setup. · `app.py`
- [Starter assignment setup](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): authoring form · Prefilled assignment with editable title, count, and due date. · `app.py`
- [Publish assignment](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): state transition · Changes local published status only. · `app.py`
- [Success and insights](https://github.com/tarwaaa/zero-gravity-cs/blob/main/app.py): status view · Separates zero real starts from illustrative future insights. · `app.py`

## Connections

- Streamlit runtime → App shell and routing: runs
- Streamlit defaults → Streamlit runtime: configures
- Dependencies → Streamlit runtime: provides runtime
- App shell and routing → Session state: reads and writes
- App shell and routing → Tutor preview: starts at
- Tutor preview → Class confirmation: continues to
- Class confirmation → Session state: stores selected class
- Class confirmation → Next-action decision: confirms class
- Next-action decision → Empty product status: finish setup
- Next-action decision → Starter assignment setup: recommended route
- Starter assignment setup → Duration calculation: uses question count
- Starter assignment setup → Session state: stores edits
- Starter assignment setup → Publish assignment: publishes
- Publish assignment → Session state: sets published status
- Publish assignment → Success and insights: shows success
- AppTest coverage → App shell and routing: validates behavior