AeThex-OS/.github/copilot-instructions.md

AeThex-OS Copilot Coding Agent Instructions

Project Overview

AeThex-OS is a modular web desktop platform built with TypeScript, React, Vite, Drizzle ORM, and Supabase. It features a multi-service architecture with clear separation between client, server, shared schema, and data migration layers. The system is designed for extensibility, rapid prototyping, and integration with external APIs and authentication providers.

Key Architectural Patterns

• Client/Server Split:
  • client/ contains the React SPA, UI components, hooks, and page logic.
  • server/ contains API routes, static asset serving, websocket logic, and Supabase integration.
  • shared/schema.ts defines all database tables and Zod validation schemas, used by both client and server.
• Drizzle ORM:
  • All database schema and types are defined in shared/schema.ts using Drizzle's pgTable and Zod schemas.
  • Migrations are managed in migrations/.
• Authentication:
  • Supabase Auth is used for user management. Profiles are linked to auth.users(id).
• Component Organization:
  • UI components are in client/src/components/ and subfolders. Shared hooks are in client/src/hooks/.
  • Pages are in client/src/pages/.

Developer Workflows

• Build:
  • Use Vite for client builds: npm run build (see vite.config.ts).
  • Server scripts are in script/ and server/.
• Test:
  • Run shell script ./test-implementation.sh for implementation checks.
• Migrations:
  • Database migrations are in migrations/. Use Drizzle migration commands as per project docs.
• Debugging:
  • Client debugging via Vite dev server. Server debugging via direct script execution or API route testing.

Project-Specific Conventions

• Type Safety:
  • All data models use Zod schemas for validation and type inference.
• Default Values:
  • Most tables use .default() for status, roles, and timestamps. See shared/schema.ts for examples.
• Extensibility:
  • New features should be added as new tables in shared/schema.ts and new components/pages in client/src/.
• Naming:
  • Use aethex_* prefix for core tables and features (e.g., aethex_sites, aethex_projects).

Integration Points

• Supabase:
  • Used for authentication and storage. See client/src/lib/supabase.ts and server/supabase.ts.
• Websockets:
  • Real-time features via client/src/hooks/use-websocket.ts and server/websocket.ts.
• API:
  • API logic in server/routes.ts and client/src/lib/api.ts.

Examples

• Schema Definition: See shared/schema.ts for Drizzle/Zod table patterns.
• Component Usage: See client/src/components/Chatbot.tsx for AI integration.
• Migration: See migrations/ for SQL migration examples.

Recommendations for AI Agents

• Always update both schema and Zod types when adding new tables or fields.
• Reference existing patterns for new features (e.g., achievements, profiles, projects).
• Use default values and type-safe patterns as shown in shared/schema.ts.
• When in doubt, follow the naming and structure conventions in existing files.

---

If any section is unclear or missing, please provide feedback for further refinement.