# Gadget Code Socket Protocol

There are three primary components in the Gadget Code architecture:

1. gadget-code:web The backend web server and interface to the database, etc.
2. gadget-code:ide The HTML5 ReactJS client running in the browser.
3. gadget-drone The worker process that executes prompt work orders using the Agentic Workflow Loop.

Socket.IO is used to connect these components and exchange messages in real-time.

## How It Works

### Getting Into A Chat Session

1. The User starts and registers at least one gadget-drone in a workspace directory.
2. The User signs into the IDE.
3. The User creates or loads a [Project](../packages/api/src/interfaces/project.ts).
4. The User selects one of their available gadget-drone instances, and either continues an exist ChatSession, or creates a new one.
5. gadget-code:web sends the [requestSessionLock](../packages//api/src/messages/ide.ts) and locks the gadget-drone to the ChatSession in the Project.
   a. The drone marks itself as locked, and will refuse all lock requests until this lock is released.
   b. The drone synchronizes the project into the workspace.
   c. The drone follows the project's instructions for configuring it for development/testing/production.
   d. The drone grants the IDE the requested session lock.
6. gadget-code:ide navigates to the Chat Session view.

The User can now begin entering prompts and editing files.

### Editing A File

When in the Chat Session view (see: [UI Design & Style Guide](../gadget-code/docs/ui-design-guide.md)), the User can select a file from the Files pane to open it in the File Editor. The mode of the File Editor depends on what's happening in the IDE at that time.

If there is a prompt work order being processed, the File Editor is read-only. The User can browse and scroll through the contents of the file and see all metadata about the file. The information and file content displayed will update as the gadget-drone process is doing it's work. But, the User is not permitted to make any changes to the displayed file content, or save the file.

If the workspace is idle (no prompt is executing), then the File Editor will open in read-write mode. The User will be able to edit the file (using the ACE editor). The User will be able to save the file. The User cannot enter a prompt or create a prompt work order while the session is in file edit mode. The user must close the File Editor and return to idle

## Protocol Sequences

### requestSessionLock

IDE:requestSessionLock => gadget-code:web => gadget-drone => gadget-code:web => IDE

The IDE initiates `requestSessionLock` when it wants to start working with a Chat Session. The event is received by the web server, which selects the drone for which it is intended based on the supplied DroneRegistration.\_id. The web server sends the message to the drone, which process it and returns the result to the web server. The web server sends the message back to the IDE.

### requestWorkspaceMode

IDE:requestWorkspaceMode => gadget-code:web => gadget-drone => gadget-code:web => IDE

The IDE initiates `requestWorkspaceMode` when it wants to request the User mode so the User can begin editing files and making changes within the project. The event is received by the web server, which sends the message to the drone. The drone processes the request and returns the result to the web server. The web server sends the message back to the IDE.