> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/commands-v3-state-machine/getting-started/project-tour.md).

# Tour of the project

All of the robot code is in `src/main/java/first/robot/`. Start reading at `Robot.java`: its header comment has the same map as this page.

```
src/main/java/first/
├── Main.java                       starts the robot program; don't change it
└── robot/
    ├── Robot.java                  builds everything once, runs the scheduler every loop
    ├── Constants.java              CAN IDs, ports, Limelight names: the wiring sheet
    ├── RobotLog.java               logging: starts the log files, robot-wide numbers
    ├── SwerveTelemetry.java        logging for the drivetrain
    ├── generated/
    │   └── TunerConstants.java     written by Tuner X; regenerate, don't edit
    ├── subsystems/
    │   ├── CommandSwerveDrivetrain.java   the swerve drive (CTRE)
    │   ├── Mechanism1.java         TEMPLATE: goes to positions (arm, elevator, wrist)
    │   ├── Mechanism2.java         TEMPLATE: spins (intake, rollers), with a game piece sensor
    │   └── Vision.java             the Limelights
    ├── superstructure/
    │   └── Superstructure.java     the state machine that runs the mechanisms together
    ├── auto/
    │   └── AutoDrive.java          "drive to this pose", for autos
    ├── util/
    │   └── Requests.java           the "ask, don't do" command for buttons and autos
    ├── simulation/
    │   └── SuperstructureSim.java  pretend physics, laptop only
    └── opmodes/                    what the Driver Station lists
        ├── teleop/DriveTeleop.java        the driver's controls
        ├── auto/ExampleAuto.java          TEMPLATE: score, fetch, score
        ├── auto/DoNothingAuto.java        the auto that does nothing
        └── utility/SysIdUtility.java      drivetrain characterization
```

## Reading order

If you're reading the code for the first time, this order builds up one idea at a time:

1. **`Robot.java`**: what exists and how it's wired together.
2. **`Constants.java`**: what's plugged in where.
3. **`subsystems/Mechanism1.java`**: the shape every mechanism follows.
4. **`util/Requests.java`**: how buttons ask for things.
5. **`superstructure/Superstructure.java`**: the state machine. This is the heart of the project.
6. **`opmodes/teleop/DriveTeleop.java`**: how buttons turn into requests.
7. **`opmodes/auto/ExampleAuto.java`**: how an auto makes the same requests.

Then read whichever part you're about to work on. The [Guide](https://docs.raidrobotics.org/commands-v3-state-machine/guide/robot-and-constants.md) has a page for each.

## Files outside the code

| File                              | What it is                                                                                                                             |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `build.gradle`                    | The build. You rarely change it.                                                                                                       |
| `vendordeps/`                     | Commands v3, Phoenix 6 and LimelightLib versions. Update with the WPILib menu › **Manage Vendor Libraries**.                           |
| `simgui-ds.json`                  | The simulator's keyboard-to-controller mapping.                                                                                        |
| `.wpilib/wpilib_preferences.json` | Team number and WPILib year.                                                                                                           |
| `src/main/deploy/`                | Files copied onto the robot controller at deploy.                                                                                      |
| `docs/`                           | These docs. See [Maintaining these docs](https://docs.raidrobotics.org/commands-v3-state-machine/reference/maintaining-these-docs.md). |

## Finding things by comment tag

The code uses a few tags in comments so you can search for them:

| Search for          | Finds                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `TODO`              | Every placeholder that must change for a real robot: IDs, ratios, gains, positions, poses. |
| `TODO (season)`     | Things that depend on the year's game.                                                     |
| `LOGGING:`          | Every place values are logged, and where to add more.                                      |
| `SIMULATION:`       | The one place the code checks whether it's in the simulator.                               |
| `RAIDSystems reads` | Lines whose shape a RAID tool depends on. Keep them as written.                            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.raidrobotics.org/commands-v3-state-machine/getting-started/project-tour.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
