Skip to Content
docsArchitecture Overview

Last Updated: 3/9/2026

Architecture Overview

The Agricultural Microworlds application is a full-stack educational platform designed to teach programming concepts through agricultural simulations.

Technology Stack

Frontend

  • Framework: React 19.1.1
  • Build Tool: Vite 7.1.7
  • Block-Based Programming: Blockly 12.3.1
  • Testing: Jest 30.2.0
  • Code Quality: ESLint, Prettier

Backend

  • Framework: ASP.NET Core (C#)
  • Language: C# (.NET)
  • Server: Kestrel

Development Environment

  • Containerization: Docker dev containers
  • Version Control: Git/GitHub
  • CI/CD: GitHub Actions

Application Architecture

High-Level Components

┌─────────────────────────────────────────────────┐
│              User Interface (React)             │
├──────────────────┬──────────────────────────────┤
│  Blockly Editor  │   Simulation Canvas          │
│  (Code Input)    │   (Visual Output)            │
└──────────────────┴──────────────────────────────┘
         │                      │
         └──────────┬───────────┘
                    │
         ┌──────────▼──────────┐
         │  Simulation Engine  │
         │   (State Manager)   │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │   ASP.NET Backend   │
         │  (Future: API/DB)   │
         └─────────────────────┘

Frontend Architecture

Component Structure

Main Application (App.jsx)

  • Root component managing workspace state
  • Splits interface between Blockly editor and simulation canvas
  • Coordinates communication between components

Blockly Section (Components/BlocklySection/)

  • Block library and coding playground
  • Custom block definitions
  • Code generation and execution

Canvas Section (Components/CanvasSection/)

  • Simulation rendering
  • Visual feedback for student code
  • Real-time state display

Simulation System

SimManager (Simulation/SimManager.js)

  • Abstract base class for simulation managers
  • Handles state updates with delta time
  • Extensible for different simulation types

Workers (Simulation/Workers/)

  • Background processing for simulation logic
  • Prevents UI blocking during complex calculations

State Management

FiniteStateManager

  • Manages application states (editing, running, stopped)
  • Coordinates transitions between states

SimulationState.js

  • Central state container for simulation data
  • Tracks crops, harvester position, yield scores, etc.

Backend Architecture

Current Implementation

  • Basic ASP.NET Core server
  • Weather forecast sample endpoint
  • Prepared for future expansion

Planned Features

  • PostgreSQL database integration
  • User authentication (CAS protocol)
  • Lesson management API
  • Student/teacher dashboard backend
  • Performance analytics

Data Flow

  1. User Input: Student drags blocks in Blockly editor
  2. Code Generation: Blockly generates executable code
  3. Execution: Code runs through simulation engine
  4. State Updates: Simulation state changes based on code
  5. Rendering: Canvas displays updated simulation state
  6. Feedback: Yield scores and completion status shown to user

Security Considerations

  • FERPA compliance for student data
  • Secure storage of PII
  • 2FA for teacher accounts
  • HTTPS-only communication
  • Input validation and sanitization

Scalability Design

  • Target: 1,000-10,000+ concurrent users
  • Docker containerization for horizontal scaling
  • Reverse proxy for load distribution
  • Database connection pooling
  • Efficient client-side simulation (reduces server load)

Accessibility

  • Screen reader compatibility
  • Keyboard navigation support
  • Colorblind-friendly visuals
  • Scalable UI for various resolutions
  • Large drag-and-drop targets for low dexterity

See Also

Blockly IntegrationDeveloper Setup