ionian/.github/copilot-instructions.md

Copilot Instructions for Ionian

Project Overview

Ionian is a full-stack content file management system focused on comic/media files. It's a pnpm monorepo with 3 packages: server (Elysia.js API), client (React+Vite SPA), and dbtype (shared TypeScript types).

Architecture & Key Patterns

Monorepo Structure

• Uses pnpm workspaces with packages/* configuration
• dbtype package provides shared types between client/server
• Server builds to dist/ directory which client proxies to via Vite dev server

Server Architecture (Elysia.js + SQLite)

• Framework: Elysia.js with TypeScript, uses Kysely for type-safe SQL queries
• Database: SQLite with custom migration system in migrations/ directory
• Core Pattern: Document-centric with content types (comic, video, etc.)
• File Watching: DiffManager + content watchers monitor filesystem changes in src/diff/
• Permissions: Role-based system in src/permission/permission.ts
• Routes: Organized by domain (/api/doc/*, /api/user/*, /api/diff/*)

Client Architecture (React + State Management)

• Router: Uses wouter (not React Router) for client-side routing
• State: Jotai atoms for global state (src/lib/atom.ts re-exports jotai)
• API: SWR for data fetching with custom hooks in src/hook/
• UI: shadcn/ui components with Tailwind CSS, dark mode support
• Build Info: Vite injects git hash/build time via __BUILD_*__ constants

Critical File Watching System

The diff system monitors content directories:

• DiffManager orchestrates multiple content watchers
• ContentDiffHandler processes filesystem changes
• Watchers register via await diffManager.register(type, watcher)
• Content changes queue in waiting lists before manual commit

Development Workflows

Build Commands

# Full deployment build (run from root)
pnpm run app:build        # Builds both client and server

# Individual package builds
pnpm run compile          # Server build
pnpm run build           # Client build (from packages/client)

# Development
cd packages/server && pnpm run dev    # tsx watch mode
cd packages/client && pnpm run dev    # Vite dev server

Database Migrations

cd packages/server && pnpm run migrate

Migrations live in migrations/YYYY-MM-DD.ts with manual version tracking.

Testing

cd packages/server && pnpm test        # Vitest unit tests
cd packages/server && pnpm test:watch  # Watch mode

Key Conventions

Import Patterns

• Server: Use .ts extensions in imports (./module.ts)
• Client: Use @/ alias for src/ directory
• Cross-package imports: import { Type } from "dbtype/mod.ts"

API Design

• RESTful routes under /api/ prefix
• Elysia schema validation with t.Object() patterns
• Permission decorators: beforeHandle: createPermissionCheck(Permission.QueryContent)
• Error handling via sendError() helper and global error handler

Component Patterns

• Page components in src/page/ directory
• Reusable components in src/components/ with ui/ subdirectory
• Custom hooks in src/hook/ for API operations
• State atoms in src/lib/atom.ts

Database Patterns

• Models in src/model/ define interfaces
• Controllers in src/db/ implement database operations
• Use Kysely query builder, not raw SQL
• Document-centric design with tag relationships

Project-Specific Context

Content Types

System supports multiple content types (comic, video) with extensible architecture. Comic content has special thumbnail/page rendering support.

Permission System

Three-tier permissions: Admin, User, Guest. Check src/permission/permission.ts for available permissions.

Client-Server Communication

• Client proxies /api/* to server during development
• Production serves client from server's static middleware
• Authentication via HTTP-only cookies with JWT refresh pattern

Common Tasks

Adding New Content Type

1. Create watcher in src/diff/watcher/
2. Register in create_server()
3. Add route handler in src/route/
4. Update dbtype if new fields needed

Adding New API Endpoint

1. Create route in appropriate src/route/*.ts file
2. Add to main router in src/server.ts
3. Define types in dbtype package if needed
4. Create client hook in packages/client/src/hook/

UI Component Development

1. Use shadcn/ui patterns in src/components/ui/
2. Use Jotai atoms for component state sharing
3. Follow existing page structure patterns