HardCode

AI Voice Synthesis & Dynamic Audio-Timer Edition (v1.5.0)
An automated, low-latency syntax memorization and multidimensional Knowledge Graph engine for computer science pedagogy and polyglot software engineering.

HardCode is an interactive, high-velocity knowledge verification and cognitive training engine engineered to establish instant recall and syntax fluency across 18 programming languages and the foundational disciplines of Computer Science and Systems Engineering.

The application models pedagogical concepts as an interactive, directed Knowledge Graph comprising 658 vertices, 786 directed relational edges, and 430 interactive multi-modal questions. HardCode features:

• Cross-Platform Female Voice Synthesis: Client-side text-to-speech engine targeting an articulate female voice persona prioritizing Web and Android compatibility, vocalizing questions upon generation and narrating pedagogical breakdowns.
• Audio-Synchronized Explanation Dwell Timers: Adaptive speech duration estimation dynamically calculating narration length with pause buffers, holding countdown bars to ensure questions never advance before spoken explanations conclude.
• Cyber-HUD Top Navigation: High-contrast dark slate (#0F172A/#1E293B) header with neon glowing accents, AI Voice HUD toggle (Key('btn_toggle_voice')), dynamic countdown progress bar, real-time accuracy sparkline, level badge, and 3D Knowledge Graph launcher.
• Granular Hierarchical Expansion: Full drill-down ontology from Galactic Core master domains down to granular leaf concepts (e.g. Computer Science $\rightarrow$ Programming Languages $\rightarrow$ Rust $\rightarrow$ Variable Declaration & Mutability, Borrow Checker & Ownership Primitives, Lifetimes, Pattern Matching, Error Handling).
• Spatial Galaxy Clustering: 3D sector separation where master domains are positioned across deep orbital distances ($R \ge 350$), while similar subtopics and leaf concepts cluster tightly ($r \le 65$) around their respective domain anchors.
• Interactive 3D Node Click Animations: Tapping nodes triggers smooth camera flight transitions, multi-ring radiating shockwaves, and rotating orbital satellites.
• Adaptive Multi-Tier Explanation Service: Throttled pedagogical intervention scaling from Concept Refresh hints to Architectural Deep Dives.
• Procedural Motion Graphics: High-energy celebratory motion graphics for streaks, level transitions, and milestones.

The live production deployment is accessible at: https://holman57.github.io/hardcode/

Curriculum content in HardCode is structured as a strict three-tier ontology:

$$\text{Core Master Domain (Level 0)} \supset \text{Sub-Topic Module (Level 1)} \supset \text{Concept Primitive (Level 2)}$$

Concepts are not isolated flashcards; they represent nodes within a directed acyclic dependency network. For example:

• Variable Declaration is an atomic concept primitive ($\text{Level 2}$).
• It is a strict subset of Programming Languages & Type Systems ($\text{Level 1}$).
• Which is in turn a constituent subdiscipline of Computer Science ($\text{Level 0}$).

Simultaneously, Variable Declaration maintains cross-cutting interdependencies with adjacent domains:

1. Systems Architecture & Memory Hierarchy: Variable allocation semantics directly depend on word alignment, register assignment, and the architectural distinction between the call stack and the heap.
2. Operating Systems: Uninitialized stack variables or unbounded pointer arithmetic interface directly with virtual memory paging, segmentation faults, and memory management unit (MMU) protections.
3. Security Engineering: Improper variable bounds handling in unmanaged languages (such as C and C++) results in stack-based buffer overflows, corrupted return pointers, and arbitrary code execution—necessitating security primitives such as Address Space Layout Randomization (ASLR), Data Execution Prevention (DEP/NX), and Stack Canaries.

graph TD
    CS["Core Domain: Computer Science"] --> PL["Sub-Topic: Programming Languages"]
    CS --> SA["Sub-Topic: Systems Architecture"]
    CS --> OS["Core Domain: Operating Systems"]

    PL --> VD["Concept Primitive: Variable Declaration & Lifetime"]
    PL --> TS["Concept Primitive: Static vs Dynamic Type Systems"]

    SA --> MH["Concept Primitive: Memory Hierarchy (L1-L3, DRAM)"]
    OS --> SF["Concept Primitive: Stack Frames & Heap Allocations"]

    VD -. "Interdependency: Allocation Semantics" .-> SF
    MH -. "Interdependency: Word Alignment" .-> VD

    VD --> C_LANG["Language Specialization: C / C++ Pointers"]
    SF --> SEC["Core Domain: Security Engineering"]
    SEC --> BOF["Concept Primitive: Buffer Overflows & Return Addresses"]
    BOF --> MITIG["Concept Primitive: ASLR, Stack Canaries, DEP/NX"]
    TS --> RUST["Language Specialization: Rust Borrow Checker & Ownership"]
    MITIG -. "Upstream Prerequisite" .-> ROP["Advanced Concept: Return-Oriented Programming (ROP)"]

User progression through the Knowledge Graph is governed by edge constraints: mastering upstream primitives awards mastery points that unlock downstream concepts and specialized language implementations.

Nodes corresponding to specific programming languages are organized along concentric orbital shells based on execution environment and type system:

1. Native Systems Languages:
   • Rust: Zero-cost abstractions, compile-time borrow checker, affine types, fearless concurrency.
   • C: Direct memory addressability, pointer arithmetic, manual heap management, POSIX interfaces.
   • C++: Resource Acquisition Is Initialization (RAII), template metaprogramming, modern move semantics.
   • C#: .NET Common Language Runtime (CLR), Task Parallel Library (TPL), Language Integrated Query (LINQ).
2. Managed Runtime and Enterprise Backends:
   • Go: Communicating Sequential Processes (CSP), lightweight goroutines, runtime channel multiplexing.
   • Java: Java Virtual Machine (JVM) bytecode, generational garbage collection, memory model invariants.
   • Kotlin: Null-safety type system, coroutine dispatchers, JVM interoperability.
   • Scala: Hybrid functional-object paradigm, higher-kinded types, actor concurrency.
3. Web, Scripting, and Systems Automation:
   • TypeScript: Static type system, structural subtyping, union/intersection types, JavaScript compilation.
   • JavaScript: Single-threaded event loop, asynchronous promises, prototype inheritance, V8 JIT engine.
   • Dart: Ahead-Of-Time (AOT) and Just-In-Time (JIT) compilation, reactive widget trees, Flutter runtime.
   • Swift: Automatic Reference Counting (ARC), protocol-oriented programming, LLVM native compilation.
   • Python 3: Dynamic typing, bytecode interpretation, Global Interpreter Lock (GIL), iterator protocols.
   • Ruby: Pure object-oriented reflection, dynamic method dispatch, metaprogramming DSLs.
   • PHP: Request-response execution lifecycle, Zend engine, modern typed properties.
   • Bash / POSIX Shell: UNIX pipelines, standard input/output/error stream redirection, POSIX shell scripts.
   • PowerShell: Object-based pipeline processing, .NET object access, Windows management automation.
   • Lua: Register-based virtual machine, coroutines, embeddable C application scripting.
   • R: S3/S4 vectorization, matrix algebra execution, statistical computing environments.

The spatial graph visualization is implemented as a directed graph $G = (V, E)$ in lib/widgets/knowledge_graph_3d_view.dart and backed by the progression engine in lib/services/progression_service.dart.

Vertices in $\mathbb{R}^3$ are mapped to screen space $(x', y') \in \mathbb{R}^2$ using perspective camera rotation and depth-divided projection:

1. Yaw Rotation (Around the $Y$-axis by angle $\theta_y$): $$\begin{pmatrix} x_1 \ y_1 \ z_1 \end{pmatrix} = \begin{pmatrix} \cos\theta_y & 0 & \sin\theta_y \ 0 & 1 & 0 \ -\sin\theta_y & 0 & \cos\theta_y \end{pmatrix} \begin{pmatrix} x \ y \ z \end{pmatrix}$$

2. Pitch Rotation (Around the $X$-axis by angle $\theta_p$): $$\begin{pmatrix} x_2 \ y_2 \ z_2 \end{pmatrix} = \begin{pmatrix} 1 & 0 & 0 \ 0 & \cos\theta_p & -\sin\theta_p \ 0 & \sin\theta_p & \cos\theta_p \end{pmatrix} \begin{pmatrix} x_1 \ y_1 \ z_1 \end{pmatrix}$$

3. Perspective Division and Optical Depth Scaling: Given focal length $f = 600.0$, camera distance $d_{\text{cam}} = 750.0$, and user zoom scale $z_{\text{zoom}} \in [0.4, 3.0]$: $$z_{\text{eff}} = \max(z_2 + d_{\text{cam}}, 25.0)$$ $$S = \frac{f \cdot z_{\text{zoom}}}{z_{\text{eff}}}$$

4. Viewport Center Mapping with Vertical Offset: To guarantee that floating graph nodes remain completely unobstructed by the collapsible bottom inspection sheet, the vertical center coordinate $y_c$ is calibrated to $38%$ of total viewport height: $$x' = \left(\frac{W_{\text{viewport}}}{2} + \Delta x_{\text{pan}}\right) + x_1 \cdot S$$ $$y' = \left(0.38 \cdot H_{\text{viewport}} + \Delta y_{\text{pan}}\right) + y_2 \cdot S$$

5. Depth-Sorted Rendering (Painter's Algorithm): Projected vertices are sorted in ascending order of transformed depth $z_2$ prior to rendering: $$\text{RenderOrder} = \text{sort}{\le z_2}({v \in V})$$ Background edges and nodes are drawn with distance attenuation ($\alpha \propto z{\text{eff}}^{-1}$), ensuring visual hierarchy and eliminating z-fighting.

Node availability is evaluated using fixed-point topological relaxation whenever mastery points are awarded:

$$\text{CanUnlock}(v) \iff \forall u \in \text{Prerequisites}(v) : \left(\text{Status}(u) \neq \text{Locked} ;\land; \text{Points}(u) \ge \text{PointsToUnlock}(v)\right)$$

Upon completing a question, the system increments the target node's points ($\Delta P$) and iteratively traverses downstream edges until no further transitions occur:

// Fixed-point topological resolution loop
bool changed = true;
while (changed) {
  changed = false;
  for (final node in nodes.values) {
    if (node.isUnlocked) continue;
    bool canUnlock = node.prerequisiteIds.every((prereqId) {
      final parent = nodes[prereqId];
      return parent != null && parent.isUnlocked && parent.points >= node.pointsToUnlock;
    });
    if (canUnlock) {
      node.status = TopicUnlockStatus.unlocked;
      changed = true;
    }
  }
}

HardCode provides five distinct cognitive evaluation modalities, each designed to test a different tier of mental representation:

1. Multiple Choice (Syntax & Conceptual Verification):
   • Evaluates syntax recognition against realistic compiler error and runtime distractors.
   • Requires disambiguating language semantics (e.g., pass-by-value vs pass-by-reference).
2. True / False Binary Rapid Evaluation:
   • Tests binary invariants, language edge cases, operator precedence rules, and algorithmic complexity limits.
   • Calibrated for sub-second rapid decision making.
3. Term & Definition Bipartite Matching:
   • Renders dual-column shuffled lists requiring the learner to establish one-to-one correspondences between architectural patterns, memory models, and definitions.
   • Requires full matrix resolution before point settlement.
4. Real-Time Sequential Pipeline Ordering:
   • Tests execution pipelines (e.g., TLS 1.3 handshakes, compiler lowering stages, TCP teardown sequences).
   • Features real-time drag-and-drop swap mechanics and directional step triggers.
5. Categorical Classification & Partitioning:
   • Requires partitioning a set of concepts into disjoint architectural bins (e.g., Symmetric vs Asymmetric Ciphers, Stack vs Heap Allocations, RISC vs CISC).
   • Validates multi-attribute taxonomy retention under time pressure.

Implemented in lib/services/adaptive_explanation_service.dart, this subsystem dynamically monitors error trajectories and intervenes when conceptual deficits are identified.

For each distinct topic $t \in T$, the engine maintains an interaction state vector:

$$\mathbf{S}_t = \big(M_t, ; C_t, ; N_t, ; \tau_{\text{last}}\big)$$

Where $M_t$ is total misses, $C_t$ is consecutive misses, $N_t$ is total attempts, and $\tau_{\text{last}}$ is the turn index of the previous remediation event.

When a learner answers incorrectly, the system escalates remediation across three pedagogically distinct tiers:

$$\text{Tier}(C_t) = \begin{cases} 1 ; (\text{Key Insight}) & \text{if } C_t = 1 \\ 2 ; (\text{Deep Dive Mechanics}) & \text{if } C_t = 2 \\ 3 ; (\text{Architectural Masterclass}) & \text{if } C_t \ge 3 \end{cases}$$

• Tier 1 (Key Insight): Concise mental model refresh, immediate mnemonic, and invariant statement.
• Tier 2 (Deep Dive Mechanics): Structural mechanics, concrete code snippets, and memory layout diagrams.
• Tier 3 (Architectural Masterclass): Low-level runtime deep dive, compiler translation phases, and hardware-level constraints.

To prevent learners from impulsively dismissing explanations during severe struggle states, the required on-screen dwell time $T_{\text{dwell}}$ scales as a function of tier and consecutive error depth:

$$T_{\text{dwell}}(C_t) = \left\lfloor 4.0 + (\text{Tier}(C_t) - 1) \cdot 3.0 + \min(C_t \cdot 1.5, ; 5.0) \right\rceil \quad \text{[seconds]}$$

To prevent cognitive fatigue and banner spam during review sessions, remediation displays are throttled by an exponential interaction interval:

$$\Delta\tau_{\text{min}} = \begin{cases} 1 & \text{if } K_t \le 1 \\ \min\left(8, ; 2^{K_t - 1}\right) & \text{if } K_t > 1 \end{cases}$$

Where $K_t$ is the cumulative count of explanations previously shown for topic $t$. If $C_t \ge 2$ (indicating urgent struggle), the threshold is halved: $\Delta\tau_{\text{required}} = \max\left(1, ; \lfloor \Delta\tau_{\text{min}} / 2 \rfloor\right)$.

Rendered by lib/widgets/motion_graphics_overlay.dart, this engine provides vector feedback for performance milestones without external raster assets:

• Particle Kinetics: Evaluated per tick using Newtonian equations of motion: $$\mathbf{p}(t + \Delta t) = \mathbf{p}(t) + \mathbf{v}(t)\Delta t, \quad \mathbf{v}(t + \Delta t) = \mathbf{v}(t) \cdot \gamma + \mathbf{a}\Delta t$$ Where $\gamma \in [0.92, 0.98]$ represents velocity damping.
• Milestone Triggers:
  • Level Initialization: Expanding cosmic starburst with radial velocity vectors.
  • Level Completion: Golden particle vortex with celestial achievement banner.
  • Streak 3 (Spark): Amber particle emitter with pulse oscillations.
  • Streak 5 (Inferno): Double-layered flame particles with kinetic acceleration.
  • Streak 10 (Hyperdrive): Cyan radiant shockwave with warp-speed light streaks.
  • Streak 20 (Singularity): Violet logarithmic spiral ($r = a e^{b\theta}$) with chromatic aberration offset passes.
• Immediate Dismissal Pipeline: All particle tickers are non-blocking and register touch-anywhere or key-down handlers to allow instant dismissal without interrupting input velocity.

HardCode includes an automated Semantic Versioning ($SemVer$) management engine implemented in scripts/bump_version.py.

The system enforces version.json as the single source of truth:

{
  "version": "1.3.0",
  "build_number": 1,
  "edition": "Security Engineering & Automated Versioning Edition",
  "updated_at": "2026-09-12T19:40:58Z"
}

Running python scripts/bump_version.py executes atomic multi-target synchronization across:

1. version.json: Increments version and monotonic build integer.
2. pubspec.yaml: Replaces version: X.Y.Z+build.
3. README.md: Updates release edition header subtitle and shield status badges.
4. assets/knowledge_graph.json: Updates internal graph_version and metadata timestamps.
5. assets/db.json: Synchronizes root database metadata schema version.

Git hooks are installed via python scripts/setup_git_hooks.py:

• Post-Merge Hook (.git/hooks/post-merge): Triggered automatically when branches are merged; calculates next minor version bump and creates a synchronized release commit.
• Pre-Push Hook (.git/hooks/pre-push): Executes the full Python automated test suite prior to allowing pushes to remote branches. Rejects pushes if tests fail or version metadata is desynchronized.

# Manual version bumping CLI commands
python scripts/bump_version.py --type patch   # 1.3.0 -> 1.3.1
python scripts/bump_version.py --type minor   # 1.3.0 -> 1.4.0
python scripts/bump_version.py --type major   # 1.3.0 -> 2.0.0
python scripts/bump_version.py --sync-only    # Re-sync across all 5 files without incrementing

• Client Runtime: Flutter Web running on the Dart SDK with HTML5 Canvas / WebGL accelerated rendering.
• Responsive Viewport Layout: Dynamic breakpoints adapting seamlessly across mobile viewports, high-density desktop displays ($4\text{K}$), and ultra-wide aspect ratios.
• Client-Side Persistence: Hive binary key-value storage (TypeAdapter serialization) for offline-first persistence of XP progress, unlocked nodes, and interaction history.
• Knowledge Graph Database: In-memory adjacency graph index loaded from serialized JSON (assets/knowledge_graph.json), supporting $O(1)$ node lookups and $O(|V| + |E|)$ topological traversals.
• Automated Test Coverage: Python validation suite (python -m unittest discover -s test) running 38 automated tests in $< 0.45\text{s}$, verifying graph integrity, question evaluators, and version bump synchronization.

• Flutter SDK ($\ge 3.1.5$)
• Python 3.10+
• Google Chrome or standard Chromium-based browser

1. Clone the repository:

   git clone https://github.com/holman57/hardcode.git
   cd hardcode

2. Execute automated verification suite:

   python -m unittest discover -s test

3. Validate and rebuild Knowledge Graph schema:

   python scripts/build_knowledge_graph.py --validate

4. Install automated Git hooks:

   python scripts/setup_git_hooks.py

5. Launch development server:

   flutter run -d chrome

This software is distributed under the MIT License.