# 2. Information Architecture

## Application Structure

Sasha Studio is a single-page React application served by an Express backend. The frontend uses React Router for client-side navigation. The backend serves the built SPA and exposes API endpoints under `/api`.

## Client-Side Routes

### Public Routes (No Auth Required)

| Route | Component | Purpose |
|-------|-----------|---------|
| `/login` | `LoginForm` | User login form |
| `/reset-password` | `ResetPasswordForm` | Password reset with token |
| `/setup` | `SetupForm` | Initial Claude API key configuration |

### Protected Routes (JWT Required)

| Route | Component | Purpose |
|-------|-----------|---------|
| `/` | `MainContent` | Main workspace -- chat + sidebar |
| `/onboarding` | `OrganizationSetupScreen` | 3-step onboarding flow |
| `/about` | `AboutPage` | System information and help |
| `/reporting` | `ReportingPage` | Analytics dashboards (admin) |

### Navigation Model

The app uses a sidebar-based navigation pattern:

```
┌─────────────────────────────────────────────┐
│ Header (logo, project selector, account)    │
├──────────┬──────────────────────────────────┤
│ Sidebar  │ Main Content Area               │
│          │                                  │
│ - Chat   │ (Chat, File Tree, Editor,       │
│ - Files  │  Knowledge, Skills, etc.)       │
│ - Know.  │                                  │
│ - Skills │                                  │
│ - Sched. │                                  │
│ - Meet.  │                                  │
│ - Git    │                                  │
│ - Tools  │                                  │
│ - Admin  │                                  │
├──────────┴──────────────────────────────────┤
│ FloatingIconBar (quick actions)             │
└─────────────────────────────────────────────┘
```

### Route Guards

- `ProtectedRoute` component wraps authenticated routes
- Checks `AuthContext` for valid JWT
- Redirects to `/login` if unauthenticated
- Admin routes check `user.isAdmin` flag

## API Endpoints

### Authentication (`/api/auth`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/status` | None | Check if system is set up |
| POST | `/register` | None | First user registration |
| POST | `/login` | None | User login, returns JWT |
| GET | `/user` | JWT | Get authenticated user info |
| POST | `/logout` | JWT | Logout (client-side token removal) |
| POST | `/forgot-password` | None | Request password reset email |
| GET | `/reset-password/verify` | None | Verify reset token validity |
| POST | `/reset-password` | None | Reset password with token |
| POST | `/change-password` | JWT | Change password (requires current) |

### File Management (`/api/files`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| POST | `/:projectName/upload-documents` | JWT | Upload files to project |
| POST | `/test-upload` | JWT | Test file upload |
| GET | `/:projectName/files/download` | JWT | Download file |
| POST | `/:projectName/move` | JWT | Move files within project |
| POST | `/move-documents-to-project` | JWT | Move files between projects |
| GET | `/view-report/:path(*)` | JWT | View generated report |

### Documentation (`/api/docs`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/resolve` | JWT | Resolve doc path |
| GET | `/download-docx` | JWT | Download as Word doc |
| GET | `/download-md` | JWT | Download as Markdown |
| GET | `/download-pdf` | JWT | Download as PDF |
| GET | `/preview-md` | JWT | Preview Markdown content |

### Skills (`/api/skills`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/` | JWT | List all skills |
| GET | `/:name` | JWT | Get skill content |
| PUT | `/:name` | JWT | Update skill |
| POST | `/` | JWT | Create new skill |
| DELETE | `/:name` | JWT | Delete skill |
| POST | `/:name/run` | JWT | Execute skill |
| POST | `/:name/execute` | JWT | Execute skill (alias) |
| PUT | `/:name/star` | JWT | Star/favorite skill |
| GET | `/:name/files` | JWT | Get skill supporting files |

### Scheduler (`/api/scheduler`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/schedules` | JWT | List all schedules |
| GET | `/schedules/:name` | JWT | Get schedule details |
| GET | `/executions` | JWT | List execution history |
| GET | `/status` | JWT | Scheduler status |
| POST | `/run/:name` | JWT | Run schedule now |
| POST | `/enable/:name` | JWT | Enable schedule |
| POST | `/disable/:name` | JWT | Disable schedule |
| POST | `/schedules` | JWT | Create schedule |
| PUT | `/schedules/:name` | JWT | Update schedule |
| DELETE | `/schedules/:name` | JWT | Delete schedule |
| POST | `/reload` | JWT | Reload scheduler |

### Git (`/api/git`)

| Method | Path | Auth | JWT | Purpose |
|--------|------|------|-----|---------|
| GET | `/status` | JWT | | Working tree status |
| GET | `/diff` | JWT | | File diffs |
| GET | `/commits` | JWT | | Commit log |
| GET | `/branches` | JWT | | Branch list |
| POST | `/commit` | JWT | | Create commit |
| POST | `/push` | JWT | | Push to remote |
| POST | `/pull` | JWT | | Pull from remote |
| POST | `/create-branch` | JWT | | Create new branch |
| POST | `/checkout` | JWT | | Switch branch |
| POST | `/generate-commit-message` | JWT | | AI-generated commit message |

### Meetings (`/api/meetings`)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| POST | `/start` | JWT | Start meeting capture |
| POST | `/stop` | JWT | Stop meeting capture |
| GET | `/status` | JWT | Meeting status |
| GET | `/transcript` | JWT | Get transcript |
| POST | `/analyze` | JWT | Analyze meeting content |
| GET | `/advisors` | JWT | List available advisors |
| POST | `/advise-now` | JWT | Get real-time advice |
| GET | `/quick-links` | JWT | Get quick links |
| POST | `/quick-links` | JWT | Create quick link |

### Admin (`/api/admin`) -- Admin Only

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/users` | Admin | List all users |
| POST | `/users` | Admin | Create user |
| PATCH | `/users/:id` | Admin | Update user |
| DELETE | `/users/:id` | Admin | Delete user |
| POST | `/users/:id/welcome-email` | Admin | Send welcome email |
| GET | `/ai-provider/status` | Admin | AI provider health |
| GET | `/ai-provider/models` | Admin | Available models |
| POST | `/ai-provider/activate` | Admin | Activate provider |
| GET | `/bedrock/status` | Admin | Bedrock status |
| POST | `/bedrock/configure` | Admin | Configure Bedrock |
| POST | `/bedrock/test` | Admin | Test Bedrock connection |
| POST | `/bedrock/switch-model` | Admin | Switch active model |
| GET | `/hook-usage-report` | Admin | Hook usage analytics |
| GET | `/hook-session-report` | Admin | Session analytics |
| GET | `/hook-timeseries-report` | Admin | Time-series analytics |
| GET | `/skill-usage-report` | Admin | Skill usage analytics |
| POST | `/refresh-stats` | Admin | Refresh analytics |
| GET | `/output-styles` | Admin | List output styles |
| POST | `/output-styles` | Admin | Create output style |
| PUT | `/output-styles/:id` | Admin | Update output style |
| DELETE | `/output-styles/:id` | Admin | Delete output style |

### Cloud Storage

**Connections** (`/api/admin/cloud-connections`) -- Admin Only:

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/` | List connections |
| POST | `/` | Create connection |
| GET | `/:id` | Get connection |
| DELETE | `/:id` | Delete connection |
| POST | `/:id/credentials` | Set credentials |
| POST | `/:id/authorize` | Start OAuth |

**Mounts** (`/api/admin/cloud-mounts`) -- Admin Only:

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/` | List mounts |
| POST | `/` | Create mount |
| PATCH | `/:id` | Update mount |
| DELETE | `/:id` | Delete mount |
| POST | `/:id/remount` | Remount drive |

**Files** (`/api/cloud/files`) -- JWT:

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/:connectionId/list` | List files |
| GET | `/:connectionId/search` | Search files |
| GET | `/:connectionId/download` | Download file |
| POST | `/:connectionId/upload` | Upload file |

### External APIs (`/api/v1`) -- API Key Required

**Projects API:**

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/projects` | List all projects |
| GET | `/projects/:projectId/meetings` | List project meetings |

**Meetings API:**

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/meetings/start` | Start meeting |
| POST | `/meetings/stop` | Stop meeting |
| GET | `/meetings/status` | Meeting status |
| GET | `/meetings/:meetingId/transcript` | Get transcript |

**Tasks API:**

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/tasks` | List tasks |
| POST | `/tasks` | Create task |
| POST | `/tasks/:name/run` | Run task |
| PUT | `/tasks/:name` | Update task |
| DELETE | `/tasks/:name` | Delete task |
| GET | `/tasks/:name/history` | Execution history |

### MCP Routes (`/api/mcp`)

All 21 MCP services follow the same pattern:

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/:service/status` | JWT | Service health |
| POST | `/:service/configure` | JWT | Configure service |
| POST | `/:service/register` | JWT | Register with Claude CLI |
| DELETE | `/:service/register` | JWT | Deregister |
| POST | `/:service/test` | JWT | Test connection |
| GET | `/cli/list` | Localhost | List registered MCPs for CLI |

### Other Routes

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| POST | `/api/bugs/report` | JWT | Submit bug report |
| POST | `/api/feedback-events` | JWT | Submit feedback event |
| POST | `/api/activity-log` | JWT | Log user activity |
| GET | `/api/executions` | JWT | Execution log list |
| GET | `/api/rules/claude-md` | JWT | Get CLAUDE.md content |
| PUT | `/api/rules/claude-md` | JWT | Update CLAUDE.md |
| GET | `/api/github/latest-release` | None | Latest release info |
| POST | `/api/cron/execute-prompt` | Localhost | Execute cron prompt |

## WebSocket Channels

| Endpoint | Purpose | Auth |
|----------|---------|------|
| `/ws` | Chat message streaming (Claude CLI output) | JWT (via query param) |
| `/shell` | Terminal shell access | JWT |

## Error & Fallback Pages

- **404**: React Router catch-all redirects to `/`
- **Auth redirect**: Unauthenticated requests redirect to `/login`
- **Setup required**: If Claude not configured, redirects to `/setup`
- **ErrorBoundary**: React error boundary wraps main content with fallback UI