# Ticket 0.2 — Directory Structure & Shared Types

**Phase**: 0 — Project Scaffolding
**Priority**: Critical (blocking)
**Depends on**: 0.1

## Description

Establish the canonical directory structure for the project and define shared TypeScript types used across modules. All subsequent tickets assume this layout and these types exist.

## Acceptance Criteria

### AC1: Server-side directory structure exists

```gherkin
Given the project root
When I list the directory tree
Then the following directories exist:
  | Path                    | Purpose                        |
  | src/bin/                | CLI entry point (TypeScript)   |
  | src/lib/                | Server-side modules            |
  | src/lib/public/         | Frontend static assets         |
  | src/lib/public/modules/ | Client-side TypeScript modules |
  | src/lib/public/icons/   | PWA icons and favicons         |
  | dist/                   | Compiled JavaScript output     |
  | docs/                   | Architecture documentation     |
  | test/                   | Test files                     |
  | test/unit/              | Unit tests                     |
  | test/integration/       | Integration tests              |
  | test/fixtures/          | Test fixtures and mocks        |
```

### AC2: Stub files exist for all core modules

```gherkin
Given the src/lib/ directory
When I list its contents
Then the following TypeScript stub files exist:
  | File                        | Purpose                              |
  | src/lib/types.ts            | Shared types used across all modules |
  | src/lib/errors.ts           | Error classes and error handling      |
  | src/lib/logging.ts          | Structured logging utility           |
  | src/lib/config.ts           | Configuration management             |
  | src/lib/daemon.ts           | Background daemon process            |
  | src/lib/server.ts           | HTTP/WebSocket server                |
  | src/lib/project.ts          | Per-project context                  |
  | src/lib/opencode-bridge.ts  | OpenCode API integration (NEW)       |
  | src/lib/sessions.ts         | Session storage                      |
  | src/lib/pty-proxy.ts        | PTY WebSocket proxy to OpenCode      |
  | src/lib/push.ts             | Push notification service            |
  | src/lib/ipc.ts              | Inter-process communication          |
  | src/lib/pages.ts            | HTML page generation                 |
```

### AC3: Frontend stub files exist

```gherkin
Given the src/lib/public/ directory
When I list its contents
Then the following TypeScript files exist:
  | File                                  | Purpose                    |
  | src/lib/public/app.ts                 | Main browser application   |
  | src/lib/public/sw.ts                  | Service worker             |
  | src/lib/public/manifest.json          | PWA manifest               |
  | src/lib/public/modules/events.ts      | Event handling             |
  | src/lib/public/modules/sidebar.ts     | File sidebar               |
  | src/lib/public/modules/terminal.ts    | Terminal UI                |
  | src/lib/public/modules/markdown.ts    | Markdown rendering         |
  | src/lib/public/modules/notifications.ts | Push notifications       |
  | src/lib/public/modules/rewind.ts      | Session rewind             |
  | src/lib/public/modules/tools.ts       | Tool execution UI          |
  | src/lib/public/modules/state.ts       | Client state management    |
  | src/lib/public/modules/input.ts       | Input handling             |
```

### AC4: Shared types module defines core interfaces

```gherkin
Given src/lib/types.ts exists
When I inspect its contents
Then it exports:
  - OpenCodeEvent: { type: string, properties: Record<string, unknown> }
  - RelayMessage: discriminated union for all WebSocket messages to the frontend
  - ProjectInfo: { slug, directory, title, openCodePort }
  - SessionInfo: { id, title, createdAt, updatedAt }
  - ConnectionHealth: { connected, lastEventAt, reconnectCount }
And all types use strict TypeScript annotations
And they are importable by all server-side modules
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| Directory tree | Unit | All required directories exist |
| Module stubs | Unit | All stubs export expected TypeScript interfaces (even if empty) |
| Shared types | Unit | `types.ts` exports all declared interfaces, compiles cleanly |
| Public assets | Unit | All frontend files exist and are valid TypeScript |
| TypeScript compilation | Fixture | `tsgo --noEmit` passes with no errors |

## Notes

- All project source files are **TypeScript** (`.ts` extension)
- `src/lib/types.ts` is the **shared types module** — imported by bridge, server, and CLI modules to avoid duplicating type definitions
- `src/lib/errors.ts` defines structured error classes (see ticket 0.5)
- `src/lib/logging.ts` provides a structured logging utility (console-based, with log levels)
- `src/lib/pty-proxy.ts` replaces `terminal-manager.ts`/`terminal.ts` — the relay proxies OpenCode's PTY WebSocket instead of managing local PTY processes
- Stub files should export empty functions/classes matching the expected API shape with proper type annotations
- This enables parallel development — different tickets can implement different modules
- Frontend `.ts` files are compiled to `.js` for browser serving (build step in ticket 0.4)
- Reference: claude-relay's structure in `../claude-relay/lib/`
