# Gadget Code IDE Style Guide

Gadget Code is an Agentic Integrated Development Environment (AIDE). It is a tool for professional software developers and project managers to use in the creation of software applications and solutions, to include: code, documentation, configuration, etc.

The brand color is #c20600, a rich red. It is to be used when printing Gadget Code.

The Gadget Code IDE (hereafter: IDE) is an HTML5 web app building using the latest stable ReactJS 19 and Tailwind CSS 4. The IDE delivers only industrial and purposeful dark theme that uses mostly blacks, near-black, and dark gray with light gray and brand color highlights.

Information-dense status and property panels. Tight margins and padding.

This is NOT a consumer news blog with giant bloated hero sections, etc. We prefer flat material design with thoughtful borders that help the eye find the information and focus on it - not distract from it.

## Theme Colors

The IDE uses the following color palette (CSS custom properties):

```
--color-brand: #c20600
--color-bg-primary: #0a0a0a (main background - pure black)
--color-bg-secondary: #121212 (panels, sidebars)
--color-bg-tertiary: #1a1a1a (cards, dropdowns)
--color-bg-elevated: #202020 (hover states)
--color-text-primary: #d4d4d4 (main text)
--color-text-secondary: #a3a3a3 (muted text)
--color-text-muted: #737373 (disabled, hints)
--color-border-subtle: #1a1a1a (subtle dividers)
--color-border-default: #2a2a2a (default borders)
--color-border-highlight: #3a3a3a (emphasis borders)
```

Font stack:

- Primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
- Code/Retro: Courier New, Courier, monospace

## View Layout (Whole Application)

The root element is given fixed positioning to fill the browser view entirely, and presents a full-width/full-height Flex column that spans the entire view.

```
#root {
  height: 100vh;
  display: flex;
  flex-direction: column;
  overflow: hidden;
}
```

The top row is the header bar (48px). The 2nd row is the content area (flex-1). The 3rd/bottom row is the status bar (32px).

### Header Bar

The header bar is basically our "window title bar" like for a desktop application:

```
GADGET CODE v1.0.0                                          [Username ▼]
```

- Left: Application title + version using Courier New font
- Right: User dropdown menu (display name, click to open)
  - Settings (placeholder)
  - Logout

Implementation: `frontend/src/components/Header.tsx`

### Status Bar

The status bar displays:

```
Ready.                                                   my-project | BUILD | ●
```

- Left: Status message ("Ready." default)
- Center-right: Active project slug (when selected), Session mode (PLAN/BUILD/TEST/SHIP/DEV)
- Right: Connection indicator (● = connected, animates when healthy)

Implementation: `frontend/src/components/StatusBar.tsx`

### Content Area

Between the header and status bars is the Content Area. It uses React Router for URL-based navigation:

| Route             | View                                              |
| ----------------- | ------------------------------------------------- |
| `/`               | Home (authenticated dashboard or unauthenticated) |
| `/projects`       | Project Manager (list view)                       |
| `/projects/:slug` | Project Manager (project selected)                |
| `/projects/new`   | New project form                                  |
| `/sign-in`        | Sign in page                                      |
| `/sign-out`       | Signs out and redirects to `/`                    |

## Unauthenticated Home View

The logged-out home view displays a "System Ready" prompt dialog.

- Font: Courier New (monospace)
- Background: #0a0a0a (pure black)
- Boxed with 2px border using border-default color
- Sign In button

Users do not "sign up" for Gadget Code - accounts are administered via CLI (`pnpm cli`).

Implementation: `frontend/src/pages/Home.tsx` - SystemReady component

## Authenticated Home View (Dashboard)

The authenticated home view presents:

```
[Welcome, Username!]
Your dashboard is under construction.
Select a project or chat session from the sidebar to get started.

[Open Project Manager]

+---------------------------+-----------------------+
|                           | Clock (AM/PM)         |
| Reserved for future        | Date                   |
| dashboard content       +-----------------------+
|                         | Projects    [+]       |
|                         | - project-1           |
|                         | - project-2           |
|                         +-----------------------+
|                         | Drones               |
|                         | - drone-alpha ●       |
|                         | - drone-beta ○       |
|                         +-----------------------+
|                         | Recent Chats          |
|                         | (loading...)         |
+---------------------------+-----------------------+
```

Components:

1. Clock - local time in AM/PM format, current date
2. Projects list - links to `/projects/:slug`, [+]/link navigates to `/projects`
3. Drones list - status indicator (green=available, yellow=busy, gray=offline)
4. Recent Chats - loading placeholder (stubbed, requires ChatSession API)

Implementation: `frontend/src/pages/Home.tsx` - DashboardSidebar component

## Project Manager View

The Project Manager presents:

```
+---------------------------+------------------------------------+
| [New Project]            | Project Inspector                  |
|---------------------------|                                  |
| Projects (2)             | Select a project to view details  |
| [project-one      ]       | or create a new project          |
| [project-two    ]        |                                |
|                         |                                |
+---------------------------+------------------------------------+
```

When a project is selected:

```
+---------------------------+------------------------------------+
| [New Project]            | Project Inspector                  |
|---------------------------|                                  |
| Projects (2)             | Name: project-one                |
| [project-one ●]           | Slug: project-one              |
| [project-two   ]          | Git URL: https://github.com/...  |
|                         | Status: active                 |
|                         | Created: 2026-04-28          |
|                         |                              |
|                         | [Delete Project]               |
|                         +-------------------------------+
|                         | Chat Sessions                 |
|                         | (loading...)               |
+---------------------------+------------------------------------+
```

Features:

- Left sidebar: Project list with [+ New Project] button
- Project Inspector: Shows name, slug, gitUrl, status, createdAt
- Delete: Confirmation before deletion
- Chat Sessions placeholder (requires ChatSession API)

URL-based: `/projects` (list), `/projects/:slug` (selected)

Implementation: `frontend/src/pages/ProjectManager.tsx`

### New Project Form

Triggered by [New Project] button or `/projects/new` route:

- Fields: Project Name*, Project Slug*, Git Repository URL
- Slug tip: "Unique identifier for the project directory"
- Submit: "Create Project" button (brand color)
- Cancel: Returns to project list

## Authentication

### Frontend Token Management

- Token stored in localStorage: `dtp_auth_token`
- User stored in localStorage: `dtp_user`
- Project stored in localStorage: `dtp_current_project`

### API Requests

All API requests include the JWT in the Authorization header:

```typescript
headers["Authorization"] = `Bearer ${token}`;
```

### Backend Session Restoration

The backend restores user sessions from:

1. `Authorization: Bearer <token>` header (JWT)
2. Express session (fallback)

The `requireUser()` middleware ensures endpoints are authenticated.

## Security

### Password Field Handling

Password credentials are NEVER exposed:

- Mongoose `select: false` on password fields in models
- Population uses `select: "-passwordSalt -password"` to exclude from queries
- Frontend User interface only includes: `_id`, `email`, `displayName`, `flags`

## Chat Session View (Planned)

The Chat Session View presents:

```
Work Area                                     | Session Status
----------------------------------------------|---------------
Chat Messages                                 | Chat: name
                                              | ID: ...
                                              | Model: ...
----------------------------------------------|---------------
[Prompt input                  ][Expand][Send]| TC | FO | SA
----------------------------------------------|---------------
Log                                           | Files
                                              |
```

Implemented components:

- Chat Messages (stubbed)
- Prompt Input (stubbed)
- Session Status sidebar (stubbed)
- File Browser (stubbed)

## Mobile Devices and Responsive Design

Nope. Gadget Code is a desktop workstation experience with one or more high-resolution displays, keyboard, mouse, webcam, microphone, and ample networking. There is no planned support for mobile devices.

Buttons are normal-sized, not bloated for finger use.

## Accessibility

The IDE wants to be as accessible as possible, providing aria tags as much as possible. Build first with an eye toward accessibility, then take a 2nd pass after the build is accepted to add accessibility enhancements.

## Tests

### Unit Tests

Location: `tests/**/*.test.ts` (excluding `tests/e2e/`)

Run: `pnpm test`

### E2E Tests

Location: `tests/e2e/**/*.test.ts`

Run: `npx playwright test`

Prerequisites: Running `pnpm dev:backend` and `pnpm dev:frontend`

Target: `https://code-dev.g4dge7.com:5174`

## Build Commands

```bash
cd gadget-code
pnpm dev:backend    # Backend on https://localhost:3443
pnpm dev:frontend  # Frontend on https://localhost:5174
pnpm build         # Build all (backend -> dist/, frontend -> frontend/dist/)
pnpm test          # Unit tests
npx playwright test # E2E tests
```