Last Updated: 4/7/2026

Sprint Planning Context

This article orients new developers joining the Agricultural Microworlds project mid-stream. It explains what has been completed, what is currently under active development, and what major features remain on the roadmap but have not yet been started.

Project Overview

Agricultural Microworlds is a K-12 educational web simulation where students use Blockly visual programming blocks to control farm equipment (tractor, harvester, seeder). The application runs entirely client-side using React 19.1.1, Vite 7.1.7, and Blockly 12.3.1. The ASP.NET Core 8.0 backend currently serves only as a static file host with a single stub WeatherForecast controller.

The project is in active development with a clear sprint roadmap through Sprint 7 (ending March 7). PostgreSQL 17 is provisioned in the devcontainer but is not yet wired up to the application—no Entity Framework context, no connection strings, no migrations exist.

Current Sprint Focus (Sprints 5-7)

According to the SpecificationDocument.md, the team is currently executing Sprints 5 through 7 with the following goals:

Sprint 5 (Jan 26 - Feb 7)

• Achieve 90%+ test code coverage: Currently only one test file exists (tests/BitmapFieldState.test.js) with comprehensive tests for the BitmapFieldState class. Additional test coverage is needed across the simulation engine, state managers, and Blockly integration.
• Improve inline documentation: JSDoc comments exist in some files (e.g., simulationEngine.js, CropState.js) but coverage is incomplete.
• Improve GitHub wiki and add top-level README: The main README.md exists with installation instructions but lacks architecture overview and contribution guidelines.

Sprint 6 (Feb 9 - Feb 21)

• Update soil simulation: The FieldTileSimManager.js file exists but contains only commented-out stub code. Soil properties (waterLevel, minerals) are defined in the field tile schema but not actively simulated.
• Update weather simulation: WeatherSimManager.js is implemented and fetches real data from the Kansas Mesonet API (mesonet.k-state.edu). It tracks cumulative GDD (Growing Degree Days) and rainfall, advancing day-by-day based on a 24-hour time accumulator.
• Harvest collection management: Harvester yield scoring is implemented in simulationEngine.js (vehicles[VEHICLES.HARVESTER].yieldScore) and displayed in the UI, but advanced collection logic may need refinement.

Sprint 7 (Feb 23 - Mar 7)

• Change what plants can be planted: The system currently supports three crop types (WHEAT, CORN, SOY) defined in CropState.js with distinct GDD requirements (1000, 1300, 900 respectively). The switch_crop_being_planted Blockly block exists and allows runtime crop selection.
• Add collection automation: Not yet implemented. This likely refers to automated harvesting logic or batch operations.

Feature Status Table

What Exists Today

Client-Side (agricultural-microworlds.client/)

• Simulation Engine (src/SimulationEngine/simulationEngine.js): 700+ line game loop managing state, physics, and async Blockly commands. Runs at variable speed with weather-based time multipliers.
• State Management (src/States/): Immutable state pattern with clone-based updates. Includes WeatherState, ImplementState, CropState, FieldTileState.
• Bitmap Field Abstraction (src/BinaryArrayAbstractionMethods/BitmapFieldState.js): Memory-efficient field storage using typed arrays (Uint8Array, Float32Array) for 300×300 tile grid.
• Simulation Managers (src/Simulation/SimManagers/):
  • WeatherSimManager.js: Fetches Kansas Mesonet data, calculates GDD, advances day/night cycle
  • CropSimManager.js: Updates crop growth based on GDD accumulation
  • TractorSimManager.js: Handles vehicle physics and collision
  • FieldTileSimManager.js: Empty stub awaiting soil logic
• Blockly Integration (src/SetUpCustomBlocks/): 14 custom blocks including movement (move_forward, turn_left, turn_right, turn_x_degrees), control (toggle_harvesting, toggle_seeding, wait_x_weeks), logic (is_over_tile, custom_compare), and variables (get_current_week, switch_crop_being_planted, change_vehicle).
• Rendering (src/Rendering/): Canvas-based rendering with camera system tracking active vehicle.

Server-Side (Agricultural-Microworlds.Server/)

• ASP.NET Core 8.0: Minimal Web API with Swagger/OpenAPI enabled in development.
• WeatherForecastController.cs: Template controller returning random weather data (not used by client).
• Static File Serving: Hosts built React app via UseStaticFiles() and MapFallbackToFile("/index.html").
• No Database Code: No DbContext, no Entity Framework packages, no migrations, no connection strings in appsettings.json.

DevContainer

• PostgreSQL 17: Running in docker-compose.yml with default credentials (postgres/postgres).
• Not Connected: No application code references the database. The POSTGRES_DB environment variable is set to “postgres” but no connection string exists in appsettings.json.

What Is NOT Started

The following features are explicitly listed in SpecificationDocument.md as “Not Started” and should not be assumed to exist:

Authentication & Authorization

• No login screens (teacher or student)
• No 2FA email system
• No CAS protocol integration
• No password reset flow
• No one-time student codes
• No session management

Teacher Features

• No class creation or management UI
• No student roster views
• No lesson assignment interface
• No lesson designer/authoring tools
• No student progress dashboards
• No performance reporting

Student Features

• No student portal or dashboard
• No lesson selection UI
• No progress tracking
• No grade display
• No curriculum path visualization

Backend Integration

• No database schema implementation (DatabaseDiagram.png exists as a plan only)
• No Entity Framework Core setup
• No API endpoints beyond the stub WeatherForecast
• No data persistence for lessons, users, or progress
• No scheduler for lesson posting

Lesson System

• No lesson data model in code
• No completion detection logic
• No end-of-lesson quizzes
• No lesson metadata (difficulty, grade level, topics)
• No lesson storage or retrieval

Planned But Not Scheduled

The SpecificationDocument.md lists these items in the “Backlog” section with no sprint assignment:

• Student/teacher dashboards
• Lesson Planner
• Education software integration (LMS connectors)
• Database setup (schema implementation, migrations)
• Block Conditions with live simulation data (conditional blocks reading field state)

Sprints 8-11 are listed as “Unplanned” in the semester goals, indicating the team has not yet committed to specific features beyond Sprint 7.

Architecture Notes

Client-Side Architecture

The simulation follows an Entity-Component-System-like pattern:

1. StateManager holds immutable state snapshots
2. SimManagers update state each frame (weather, crops, tractor)
3. simulationEngine orchestrates the game loop and async Blockly commands
4. Rendering reads state and draws to canvas

State updates use a clone-then-mutate pattern: old state is cloned, managers write to the clone, then the clone is committed as the new official state. This enables time-travel debugging and ensures managers don’t interfere with each other.

Backend Architecture

The backend is currently a minimal SPA host. The SpaProxyLaunchCommand in the .csproj file points to npm run dev, which starts Vite’s dev server. In production, the backend would serve pre-built static files from the client’s dist folder.

No API routes exist beyond the template WeatherForecast endpoint. The client fetches weather data directly from the Kansas Mesonet public API (https://mesonet.k-state.edu/rest/stationdata ), bypassing the backend entirely.

Development Workflow

Based on package.json scripts and README.md:

1. Open GitHub Codespace or devcontainer
2. Clear /tmp/* if running in recovery mode
3. Rebuild container if needed
4. cd agricultural-microworlds.client
5. npm run build (builds Vite bundle)
6. npm run dev (starts ASP.NET backend, which proxies to Vite)

The dev script runs cd ../Agricultural-Microworlds.Server && dotnet run, which launches the ASP.NET server. The server’s SpaProxy configuration forwards requests to Vite’s dev server at https://localhost:63119 .

Testing Status

Only one test file exists: tests/BitmapFieldState.test.js with 11 test cases covering:

• Array initialization
• Field initialization with starting values
• Clone functionality
• Adding variables dynamically
• Setting/getting tile data
• Setting/getting individual variables

No tests exist for:

• Simulation engine game loop
• State managers (weather, crop, tractor)
• Blockly code generation
• Rendering logic
• React components

Sprint 5’s goal of 90%+ coverage will require significant test authoring across all these areas.

Key Decisions & Constraints

Technical Constraints

• Must run on school computer specs (low-end hardware)
• Must scale to 1,000-10,000 users (not yet load-tested)
• Must conform to FERPA (no PII handling implemented yet)
• Must conform to ADA (accessibility features not implemented)
• Must support <5 second load time (not yet measured)

Design Decisions

• Client-side simulation: All game logic runs in the browser. No server-side physics or state management.
• Real weather data: Uses Kansas Mesonet API for authentic agricultural conditions.
• GDD-based crop growth: Crops mature based on accumulated Growing Degree Days, not simple timers.
• Multi-vehicle system: Harvester and Seeder are independent entities, not modes of a single tractor.
• Blockly for programming: Visual blocks compile to JavaScript executed by the simulation engine.

Common Pitfalls for New Developers

1. PostgreSQL is not connected: Do not assume database queries will work. The database exists in Docker but has no application code connecting to it.
2. Backend is minimal: The ASP.NET server is currently just a static file host. Do not expect REST APIs for lessons, users, or progress.
3. No authentication: There is no login system. Do not reference user sessions or permissions in code.
4. Lesson system is planned, not built: The SpecificationDocument describes lesson features in detail, but none of that code exists yet.
5. Test coverage is low: Only BitmapFieldState has tests. Assume other code is untested.

Next Steps for New Developers

1. Read the SpecificationDocument.md: Understand the full vision for teacher/student portals, lesson systems, and authentication.
2. Explore the simulation engine: Start with simulationEngine.js to understand the game loop, then trace through state managers.
3. Run the application: Follow the README.md installation steps to see the working simulation in your browser.
4. Check current sprint goals: Review Sprints 5-7 in SpecificationDocument.md to see what the team is actively building.
5. Identify testing gaps: Look for untested code in src/ and write Jest tests to improve coverage toward the 90% goal.

What’s Next

• Simulation Engine Architecture: Understand how the game loop, SimManagers, and state updates work together at a deeper technical level.
• Installation & Setup: Get the development environment running and see the simulation in your browser.
• Testing Guide: Learn the Jest setup and how to contribute tests toward the Sprint 5 coverage goal.