weevil/templates/testing/ARCHITECTURE.md

# Weevil Motor Cycle Demo - Architecture Overview

## What This Example Demonstrates

This is a minimal but complete FTC robot project showing how Weevil enables:
1. Clean separation of business logic from hardware
2. Unit testing on Windows JRE without FTC SDK
3. Professional software architecture for robotics

## The Problem Weevil Solves

Traditional FTC projects:
- Force you to edit SDK files directly (TeamCode folder)
- Mix hardware dependencies with business logic
- Make testing nearly impossible without a physical robot
- Create monolithic OpMode classes that are hard to maintain

## Weevil's Solution

### Three-Layer Architecture

```
┌─────────────────────────────────┐
│  OpMode (Integration Layer)    │  ← Only runs on robot
│  - Wires everything together   │
└─────────────────────────────────┘
              ▼
┌─────────────────────────────────┐
│  Business Logic Layer           │  ← Runs everywhere!
│  - MotorCycler                  │     Tests on Windows JRE
│  - Pure Java, no FTC deps       │
└─────────────────────────────────┘
              ▼
┌─────────────────────────────────┐
│  Hardware Abstraction Layer     │  ← Interface + implementations
│  - MotorController (interface)  │
│  - FtcMotorController (robot)   │
│  - MockMotorController (tests)  │
└─────────────────────────────────┘
```

## File Breakdown

### Hardware Abstraction (`src/main/java/robot/hardware/`)

**MotorController.java** (17 lines)
- Interface defining motor operations
- No FTC SDK dependencies
- Default methods for convenience

**FtcMotorController.java** (19 lines)
- Wraps FTC SDK's DcMotor
- Only compiled when building for robot
- Implements MotorController interface

**MockMotorController.java** (27 lines - in test/)
- Test implementation
- Tracks state for assertions
- No hardware required

### Business Logic (`src/main/java/robot/subsystems/`)

**MotorCycler.java** (95 lines)
- Pure Java state machine
- Time-based motor cycling
- Zero FTC SDK dependencies
- Fully testable in isolation

Core design:
```java
public void update(long currentTimeMs) {
    long elapsed = currentTimeMs - stateStartTime;
    
    switch (state) {
        case OFF:
            if (elapsed >= offDurationMs) {
                motor.setPower(motorPower);
                state = ON;
                stateStartTime = currentTimeMs;
            }
            break;
        case ON:
            if (elapsed >= onDurationMs) {
                motor.setPower(0.0);
                state = OFF;
                stateStartTime = currentTimeMs;
            }
            break;
    }
}
```

### Integration (`src/main/java/robot/opmodes/`)

**MotorCycleOpMode.java** (44 lines)
- FTC OpMode
- Connects hardware to logic
- Minimal glue code

### Tests (`src/test/java/`)

**MotorCyclerTest.java** (136 lines)
- 9 comprehensive unit tests
- Tests timing, state transitions, edge cases
- Runs in milliseconds on PC
- No robot or FTC SDK required

Test coverage:
- Initialization
- State transitions (OFF→ON, ON→OFF)
- Full cycle sequences
- Time tracking
- Stop functionality
- Edge cases (default power, tiny power values)

## Development Workflow

### 1. Write Code Locally
Edit files in `src/main/java/robot/` - your IDE works perfectly

### 2. Test Immediately
```bash
gradlew test
```
- Runs in seconds on Windows
- No robot connection needed
- Full JUnit reports

### 3. Deploy to Robot
```bash
build.bat    # Compiles everything, builds APK
deploy.bat   # Copies APK to robot
```

## Why This Architecture Matters

### For Students
- Learn professional software engineering
- Write testable code
- Build confidence through tests
- Debug logic without hardware

### For Teams
- Multiple programmers can work simultaneously
- Test changes before robot practice
- Catch bugs early (compile-time, not drive-time)
- Build more complex robots with confidence

### For Competitions
- More reliable code
- Faster iteration cycles
- Better debugging capabilities
- Professional development practices

## Technical Benefits

1. **Dependency Injection**: MotorCycler receives MotorController through constructor
2. **Interface Segregation**: Clean interface with single responsibility
3. **Testability**: Mock implementations enable isolated testing
4. **Separation of Concerns**: Hardware, logic, and integration are distinct
5. **Open/Closed Principle**: Easy to extend without modifying core logic

## Comparison to Traditional FTC

| Traditional FTC | Weevil Architecture |
|----------------|---------------------|
| Edit SDK files directly | Your code stays separate |
| Mix hardware and logic | Clean separation |
| No unit tests | Comprehensive tests |
| Debug on robot only | Debug on PC first |
| Monolithic OpModes | Modular subsystems |
| Hard to maintain | Easy to understand |

## Extending This Example

Want to add more features? Keep the pattern:

1. **Add Interface** in `hardware/` (e.g., `ServoController`)
2. **Implement Logic** in `subsystems/` (e.g., `ArmController`)
3. **Create Mock** in `test/hardware/`
4. **Write Tests** in `test/subsystems/`
5. **Wire in OpMode** - just a few lines of glue code

The architecture scales from simple examples like this to complex multi-subsystem robots.

## Real-World Application

This demo shows the fundamentals. Real robots would have:
- Multiple subsystems (drivetrain, arm, intake, etc.)
- Command pattern for complex sequences
- State machines for autonomous
- Sensor integration (same abstraction pattern)
- Configuration management

All testable. All maintainable. All professional.

---

**This is what Weevil enables: writing robot code like professional software.**