pi sills

2026-02-23 22:52:27 +00:00
parent 8fb96c7cf8
commit 2126f3912e
35 changed files with 1126 additions and 137 deletions
@@ -2,26 +2,50 @@

 Guide for agentic coding assistants working in the Officer monorepo.

+## What Is Officer
+
+Officer is an **AI-powered intranet server** for small and medium businesses. It's a self-hosted platform that gives each team member a personal AI assistant, file storage, terminal, code editor, workspaces, and project management — all under centralized admin control.
+
+**Think of it as**: a self-hosted, AI-native company intranet where every employee gets their own workspace with shared organizational resources and automation.
+
+### Multi-User Architecture
+
+- **Role hierarchy**: Member → Admin → Owner → Super Admin
+- **Bootstrap flow**: First user registers as Super Admin, then invites the team
+- **Per-user isolation**: Files, sessions, settings, workspaces, and tasks are scoped per user under `$DATA_PATH/{email}/`
+- **Shared org resources**: Global tasks/skills/processes, server-level settings (SMTP, AI providers, TTS/STT/OCR), pluggable applications and resources
+- **Multi-scope resolution**: Tasks, skills, and processes resolve user → global → native (built-in), enabling org-wide shared automation
+
+### Core Capabilities
+
+1. **AI Chat** — Multi-provider (Claude, OpenCode, Pi-Mono) with sessions, attachments, speech-to-text, slash commands
+2. **File Browser** — Full filesystem access per user (upload, mkdir, copy, move, delete)
+3. **File Viewer** — Preview video, images, code, text, markdown
+4. **Terminal** — WebSocket-based PTY terminal with Docker sandboxing
+5. **Code Editor** — Monaco-based IDE with file tabs
+6. **Projects** — Project management with per-project workspace layouts, git init
+7. **Workspaces** — Customizable panel-based layouts (split, resize, swap, drag)
+8. **Automation/Skills/Tasks/Processes** — Markdown-based capability definitions with YAML frontmatter
+9. **Dev Server** — Start/stop project dev servers with auto-port discovery and live proxy
+10. **Dashboard Widgets** — Clock, weather, pomodoro, daily goals, quick notes
+11. **Settings** — User preferences, server config, resource management
+
 ## Quick Start Commands

 ### Development

 ```bash
 bun dev              # Dashboard + API server (port 5000)
-bun dev:tracking    # Tracking server (port 5001)
-bun dev:experiments # Experiments server
-bun dev:emailer     # Emailer workspace
+bun dev:emailer      # Emailer workspace
 ```

-### Building & Database
+### Building

 ```bash
 bun run prebuild              # Run prebuild tasks
+bun run build:web             # Build web app
 bun run build:dashboard       # Build dashboard
 bun run build:editor          # Build editor (app + extension + runtime)
-bun run build:runtime         # Build all runtime scripts
-bun run db:gen && db:push     # Generate & push officer_db migrations
-bun run db:gen:stats && db:push:stats  # Generate & push statistics_db
 ```

 ### Code Quality
@@ -29,11 +53,82 @@ bun run db:gen:stats && db:push:stats  # Generate & push statistics_db
 ```bash
 bun format          # Format all files (Prettier, required before commit)
 bun format:check    # Check formatting without writing
-bunx tsgo           # TypeScript type checking (comprehensive, slow)
+bunx tsgo           # TypeScript type checking
 ```

 **Note:** No automated tests configured yet. Always run `bun format` before committing.

+## Project Structure
+
+```
+src/
+├── apps/
+│   └── officer-web/          # Main web UI (React 19)
+│       ├── Screens/
+│       │   ├── Authentication/   # Login, verify, reset password
+│       │   └── Dashboard/        # All main screens (Home, Files, Chat, Terminal, Projects, etc.)
+│       ├── state/                # App-specific state hooks
+│       ├── lib/                  # Utilities
+│       └── locales/              # i18n translations
+│
+├── servers/
+│   ├── api/                  # REST API (Hono, port 5000)
+│   │   ├── auth/             # Authentication (JWT + WebAuthn passkeys)
+│   │   ├── users/            # User management (invite, CRUD)
+│   │   ├── sessions/         # Multi-provider chat sessions
+│   │   ├── workspaces/       # Workspace & project state
+│   │   ├── tasks/            # Task definitions (CRUD + chat)
+│   │   ├── skills/           # Skill definitions (CRUD + chat)
+│   │   ├── processes/        # Process definitions (CRUD + chat)
+│   │   ├── file-browser/     # Filesystem access (multi-root)
+│   │   ├── terminal/         # WebSocket PTY terminal
+│   │   ├── dev-server/       # Project dev server management
+│   │   ├── pi/               # AI agent integration
+│   │   ├── scrape/           # Web scraping (Playwright)
+│   │   ├── upload/           # File uploads
+│   │   ├── settings/         # User settings & state
+│   │   ├── server-settings/  # Server-wide config (SMTP, AI, TTS, etc.)
+│   │   ├── dock/             # Dock configuration
+│   │   ├── plans/            # Markdown plans
+│   │   ├── task-logs/        # Task execution logs
+│   │   └── landing-page-data/# Registration status
+│   └── _middlewares/         # Auth, rate limiting, CORS, body parsing
+│
+├── databases/
+│   └── officer_db/           # JSON file-based auth store (users, passkeys, tokens)
+│
+└── workspaces/               # 13 shared packages
+    ├── types/                # Central type re-exports
+    ├── definitions/          # Constants, enums (roles, statuses, devices)
+    ├── config/               # URL configs, env vars
+    ├── helpers/              # cn(), formatters, slug, debounce, queue
+    ├── hooks/                # 90+ hooks (useClient, useForm, useAuth, etc.)
+    ├── state/                # React Query state hooks (useSettings, useChatSessions, etc.)
+    ├── components/           # 89 components (shadcn/ui base + custom)
+    ├── officerdev/           # Core workspace/panel framework + 11 built-in apps
+    ├── i18n/                 # Internationalization
+    ├── injector/             # DOM manipulation for visual editing
+    ├── widgets/              # Dashboard widgets (clock, weather, pomodoro, etc.)
+    ├── emailer/              # React-email templates + SMTP
+    └── sounds/               # Audio feedback library
+```
+
+## Path Aliases
+
+- `@/` → `src/apps/officer-web/`
+- `@@/` → `src/servers/`
+- `@/components/*` → `src/workspaces/components/*`
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Language**: TypeScript 5.9 (strict mode, verbatimModuleSyntax)
+- **Frontend**: React 19, React Router, React Query, Tailwind CSS, shadcn/ui
+- **Backend**: Hono framework, JWT auth, WebAuthn passkeys
+- **Storage**: JSON file-based (auth store + user data), no traditional DB for most data
+- **Build**: Vite
+- **AI**: Claude Agent SDK, multi-provider support
+
 ## Code Style Guide

 ### Imports
@@ -48,9 +143,15 @@ import { useExperiment } from 'hooks/use-experiment';
 import { formatDate } from '../helpers';
 ```

+Type-only imports required (verbatimModuleSyntax):
+```ts
+import { ActionModals, type ActionModalsTypes } from './ActionModals';
+import type { FormEvent } from 'react';
+```
+
 ### TypeScript

- Strict mode always - no `any`
+- Strict mode always — no `any`
 - Prefer `type` over `interface`
 - Colocate prop types with components as named exports
 - Early returns for null/undefined guards
@@ -61,12 +162,11 @@ import { formatDate } from '../helpers';
 - Arrow functions for simple/one-liners
 - Regular functions for complex multi-line logic
 - Named exports only (never default exports)
+- Extract params type when signature gets long (no multiline params)

 ```ts
 export const formatDate = (ts: number) => new Date(ts).toLocaleDateString();
-export function calculateStats(data: DataPoint[]) {
-  /* ... */
-}
+export function calculateStats(data: DataPoint[]) { /* ... */ }
 ```

 ### React Components
@@ -82,23 +182,13 @@ export const Card = ({ title, onClick }: CardProps) => <div onClick={onClick}>{t

 ### State Management

- **Manager pattern** for complex hooks - return object with state + methods
- **Colocation** - all feature state in one hook
- **Derived state** - compute in hook, not in components
-
-```ts
-export const useExperimentManager = (id: number) => {
-  const [exp, setExp] = useState<Experiment | null>(null);
-  const isActive = exp?.status === 'running';
-  return {
-    exp,
-    isActive,
-    update: (data) => {
-      /* ... */
-    },
-  };
-};
-```
+- **React Query** for server state
+- **useGlobal()** for UI state (backed by query cache, no Context needed)
+- **useWorkspacesState()** for persistent workspace layouts (server-synced)
+- **useQueryState()** for URL-synced state
+- **usePanelChannel()** for inter-panel pub/sub communication
+- **Manager pattern** for complex hooks — return object with state + methods
+- **Derived state** — compute in hook, not in components

 ### Naming Conventions

@@ -118,40 +208,13 @@ export const useExperimentManager = (id: number) => {

 - Use try/catch for async operations
 - Include context in error messages (IDs, resource names)
- Log with `console.error` and re-throw appropriately
- Handle database connection errors explicitly
-
-### Async/Await
-
- Always use async/await (never .then() chains)
- Minimize nesting
-
-## Project Structure
-
- `src/apps/dashboard/` - Admin UI (React 19)
- `src/apps/editor/` - Visual editor
- `src/servers/api/` - REST API (Hono, port 5000)
- `src/servers/tracking/` - Event collection (port 5001)
- `src/databases/` - PostgreSQL schemas (3 DBs: officer_db, statistics_db, ephemeral_db)
- `src/workspaces/` - Shared: components, hooks, helpers, types
-
-## Path Aliases
-
- `@/` → `src/apps/dashboard/`
- `@@/` → `src/servers/`
-
-## Tech Stack
-
- **Runtime**: Bun
- **Language**: TypeScript 5.9 (strict mode)
- **Frontend**: React 19, React Router, React Query, Tailwind CSS, shadcn/ui
- **Backend**: Hono, PostgreSQL, Drizzle ORM
- **Build**: Vite
+- Always async/await (never .then() chains)

 ## General Guidelines

- **Database-first** approach - schema → API → UI
- **Self-documenting code** - clear naming, minimal comments
- **Explicit over implicit** - no magic
- **Workspace dependencies** - use `workspace:*`
- **Environment variables** - use `.env`, access directly in code
+- **Database-first** approach — schema → API → UI
+- **Self-documenting code** — clear naming, minimal comments
+- **Explicit over implicit** — no magic
+- **Workspace dependencies** — use `workspace:*`
+- **Multi-user aware** — always consider user isolation and role-based access when adding features
+- **File-based storage** — user data lives under `$DATA_PATH/{email}/`, respect the per-user boundary