YoRHa-HexFlow: Hex Instruction Orchestrator

YoRHa-HexFlow is a highly visual hexadecimal instruction orchestration tool designed to simplify complex low-level binary protocol design through a Block Flow approach. Its design is inspired by the UI style of Nier: Automata, emphasizing interaction fluidity and immersion.

✨ Key Features

1. Visual Orchestration

• Drag & Drop Blocks: Based on @dnd-kit, supporting infinite nested block dragging and sorting.
• Dynamic Swimlanes: Automatically generates hierarchical swimlane views based on data structure.
• Smart Connections: Automatically draws logical relationships between blocks (e.g., checksum references, length calculation references).

2. Powerful Logic Engine

• Real-time Formula Calculation: Supports dynamic formulas like ([FieldA] + 10) / 2, with real-time preview of calculation results on the frontend.
• Auto Counters & Time Accumulation: Built-in intelligent blocks like AUTO_COUNTER and TIME_ACCUMULATOR.
• Multi-base Support: Property panels support seamless switching between HEX/DEC/BIN input.

3. Engineering & Quality

• SRP Architecture: Strictly follows the Single Responsibility Principle, with logic hooked and components atomized.
• Full-link Testing:
  • Integrated Vitest + React Testing Library.
  • 100% test coverage for core hooks.
  • Includes smoke tests to prevent crashes.

---

🚀 Quick Start

1. Database Setup

Create the MySQL database and initialize the schema.

# Login to MySQL and create the database
mysql -u root -p
CREATE DATABASE tc CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
USE tc;

# Execute schema and seed data
SOURCE backend/db/migrations/schema.sql;
SOURCE backend/db/migrations/seed_data.sql;

2. Backend Service

Provides data persistence and core business APIs.

# Windows
python -m venv venv
.\venv\Scripts\activate
pip install -r backend/requirements.txt

# Start (http://127.0.0.1:8000)
python -m uvicorn backend.main:app --reload

3. Frontend Interface

An interactive interface built with React 18 + Vite.

cd frontend
npm install

# Start (http://localhost:5173)
npm run dev

4. Run Tests

Ensures the safety and stability of code modifications.

cd frontend
npm run test

---

🏗️ Architecture

graph TD
    UI[Frontend UI] -->|Ref/Select| Hooks[Custom Hooks]
    Hooks -->|Data Flow| Logic[Business Logic]
    Logic -->|REST API| API[Backend FastAPI]
    
    subgraph Frontend [React Layer]
      Hooks --> useInstructionData
      Hooks --> useSelectionSystem
      Hooks --> useInstructionLanes
      Hooks --> useCanvasConnections
    end
    
    subgraph Utils [Shared Utilities]
      Logic --> formula.js[Formula Engine]
      Logic --> constants.js[Constants]
    end

Loading

For detailed technical specifications, please refer to: SPECIFICATION.md

---

📜 Directory Structure

/backend
    /main.py            # FastAPI entry point
    /models.py          # Pydantic data models
    
/frontend
    /src
        /components     # Atomic UI components (Block, PropertiesPanel)
        /hooks          # Business logic Hooks (Data, Selection)
        /pages          # Page-level containers (Instruction, Canvas)
        /utils          # Pure function utilities (Formula, Hex)
        /constants.js   # Global constant definitions
    /src/hooks/__tests__ # Unit test suite

⚠️ Development Guidelines

1. Single Responsibility: No single file should exceed 400 lines; complex logic must be extracted into Hooks.
2. Test-Driven: npm run test must be run after modifying core logic.
3. DRY Principle: Avoid Magic Strings; use constants.js.

---

Glory to Mankind.