# Technical Design

## Boundaries

- `bin/road-workbench.js` owns process startup and creates an import session/workspace.
- `workbench/server.js` owns HTTP routes and session-local files; it continues to call `compileInput()` for compilation.
- `workbench/client/index.html` and `workbench/client/app.js` add the upload/bootstrap state only; existing editing panels remain unchanged.
- `src/compile/compiler.js` and `src/osm.js` remain the source of truth for input validation and OSM processing.

## Data Flow

1. CLI starts a workbench with an optional existing `--input` for compatibility, or with no input for the new import-first flow.
2. The browser submits multipart OSM content (bounded by a server upload limit) to a new session/import endpoint.
3. The server validates the filename/content, creates a unique workspace directory under a configured workbench data root, and writes:
   - `source.osm`
   - `native-road-overrides.json` with the existing empty schema
   - `native-traffic-signals.json` with the existing empty schema
   - `RoadCompilerInput.json` using conservative defaults and workspace-relative output paths
4. The server calls `compileInput()` and swaps the active session from the import screen to the existing state/map view.
5. Existing routes operate against the active session's `area` object. A failed import/compile removes only the new staging directory and leaves any prior active session untouched.

## Defaults and Compatibility

- Area id is derived from a sanitized user-provided name or uploaded basename, with a unique suffix when necessary.
- `options.edgeLines` and `options.junctionTemplates` use the same shape required by `validateInput()`; no new compiler options are introduced.
- Existing `--input RoadCompilerInput.json` startup remains supported by adapting it into the same active-session context.
- The server binds to localhost as it does today and does not add authentication or remote persistence.

## Error and Recovery

- Reject empty/non-XML uploads, oversized bodies, malformed OSM, and compile failures with JSON errors suitable for the browser.
- Stage all files before switching the active session; cleanup on failure.
- Keep workspace directories recoverable on disk; do not delete an existing user workspace during a new import.

## Testing Strategy

- Unit/integration tests for workspace initialization, default input generation, upload size/content validation, and failed-import cleanup.
- HTTP smoke test for import -> state -> compile/export using the existing fixture OSM.
- Existing compiler and fixture tests remain the regression gate.