Branch Predictor Simulator

Warning

This project is archived and no longer maintained. It was developed as an experimental academic tool, but its user interface was never completed to a standard suitable for a public release. The source code is preserved for reference only.

Local web application for studying and solving branch predictor exercises from the Computer Structure course at Universidad Complutense de Madrid.

The app can work from didactic C, RISC-V, or a manual branch sequence. It runs canonical simulations, projects dynamic tables, calculates statistics, checks user answers, and exports sessions/results.

Source Of Truth

The living project documentation is:

• docs/REQUISITOS.md: v1 functional scope and requirements.
• docs/ARQUITECTURA.md: domain model, layers, contracts, and design patterns.
• docs/POLITICA_QA.md: test policy, quality gates, and QA responsibilities.
• docs/RELEASE_CHECKLIST.md: local v1 release checklist.
• docs/RELEASE_CHECKLIST_RUNS.md: completed release checklist evidence.
• docs/SECURITY_TASKS.md: dependency audit findings and upgrade tasks.
• docs/DECISIONES_TECNICAS_Y_AGENTES.md: technical decisions, tools, and Codex agents.
• .codex/AGENTES.md: operational cheat sheet for subagents.
• ref_docs/Problems.pdf: official branch predictor exercises.
• ref_docs/Theory.pdf: course reference material.

docs/REQUISITOS.md and docs/ARQUITECTURA.md drive implementation decisions.

Current Status

Archived experimental project. No official release was published. Although the local validation work was completed, the user interface did not reach the quality required for a public release.

Implemented:

• Vite + React + TypeScript scaffold.
• Layered architecture: domain, application, infrastructure, and presentation.
• Canonical simulation engine with partial/full execution, loop expansion, and trace snapshots.
• Main v1 predictors: one-level, two-level (n,m), global correlated, gshare, gselect, and local correlated.
• LSB, manual, XOR, and concatenation indexers.
• Trace-derived statistics: hits, misses, rates, memory, used entries, and aliasing.
• Rich trace-derived table projection, compact calculations, CSV/Markdown table export, and YAML session export/import.
• Initial RISC-V parser for conditional branches, labels, addresses, and comments.
• Didactic C translator for loop/branch exercises; it is not a general C compiler.
• Editable manual sequence table with branch id, outcome, index, address, comments, and raw text compatibility for repeated ranges.
• Statistic and table answer checking.
• Official templates for exercises 1, 2, 3, 4, 5, and 7 as versioned, engine-verified data.
• Functional MUI/Zustand UI for templates, variants, editors, TanStack-powered table, statistics, checking, calculations, and import/export.
• Tool-style UI with a left control sidebar, source tabs, CodeMirror 6 editors, table-centered workspace, export menu, and collapsible YAML import.
• Validated JSON predictor configuration editor for custom v1 predictor settings.
• Step forward, step backward, full run, and reset through the canonical trace.
• Playwright e2e coverage for run, reveal, check, Markdown export, YAML export, manual sequence editing, YAML import, template/variant selection, exam leakage, and responsive smoke checks.
• Manual visual/responsive/accessibility review recorded in the release checklist evidence.
• GitHub Actions workflows for CI and release-time GitHub Pages deployment.
• Dependency audit currently reports 0 vulnerabilities.

Stack

• TypeScript
• Vite
• React
• MUI Material UI
• CodeMirror 6
• Zustand
• TanStack Table
• Zod
• yaml
• Vitest
• Testing Library
• Playwright
• ESLint + Prettier

Local Development

Windows helper:

project.bat
project.bat start
project.bat install
project.bat dev
project.bat check
project.bat clean

Double-click project.bat to build the production app, open the browser, and serve it locally at http://127.0.0.1:4173. Keep the terminal open while using the simulator.

Direct npm commands:

npm.cmd install
npm.cmd run dev
npm.cmd test
npm.cmd run test:e2e
npm.cmd run lint
npm.cmd run build

Use project.bat for the common Windows workflow, or npm.cmd directly if you want to run individual commands.

Required gates before closing code changes:

npm.cmd test
npm.cmd run test:e2e
npm.cmd run lint
npm.cmd run build

GitHub Automation

The repository includes GitHub Actions workflows:

• .github/workflows/ci.yml: runs tests, e2e, lint, build, and audit on main, pull requests, and manual dispatch.
• .github/workflows/release-pages.yml: runs the release gates when a GitHub Release is published, builds the app with the GitHub Pages base path, and deploys dist/ to GitHub Pages.

The release-gated Pages workflow was prepared but never used for an official release. It is retained as part of the project's history.

Structure

src/
+-- domain/
|   +-- correction/
|   +-- indexing/
|   +-- predictors/
|   +-- shared/
|   +-- simulation/
|   +-- source/
|   +-- stats/
+-- application/
|   +-- projectors/
|   +-- SimulationSessionService.ts
+-- infrastructure/
|   +-- export/
|   +-- persistence/
|   +-- predictors/
|   +-- templates/
+-- presentation/
    +-- components/
    |   +-- editors/
    +-- composition/
    +-- screens/
    +-- stores/
    +-- theme/
docs/
ref_docs/

Key rule: the domain does not depend on React, MUI, Zustand, YAML, the DOM, or browser storage. The UI calls the application layer and consumes projections derived from the canonical trace.