AeThex-OS/replit.md

# AeThex Ecosystem

## Overview

AeThex is a full-stack web application that serves as an "Operating System for the Metaverse." The platform is built around a "Holy Trinity" architecture concept: **Axiom** (foundational principles), **Codex** (certification/credential system), and **Aegis** (security/protection layer). The system transforms talent into certified "Metaverse Architects" through a structured curriculum and credentialing process.

The application includes:
- Public-facing landing pages explaining the ecosystem
- An "AeThex Passport" credential certification system
- A simulated "Terminal" interface demonstrating security features
- An admin dashboard for managing architects, projects, and credentials
- Real-time metrics and threat monitoring displays

## User Preferences

Preferred communication style: Simple, everyday language.

## System Architecture

### Frontend Architecture
- **Framework**: React 18 with TypeScript
- **Routing**: Wouter (lightweight React router)
- **State Management**: TanStack React Query for server state
- **Styling**: Tailwind CSS v4 with custom CSS variables for theming
- **UI Components**: shadcn/ui component library (New York style) built on Radix UI primitives
- **Animations**: Framer Motion for page transitions and UI effects
- **Charts**: Recharts for data visualization
- **Fonts**: Custom display fonts (Oxanium, JetBrains Mono, Share Tech Mono) for tech/cyberpunk aesthetic

### Backend Architecture
- **Runtime**: Node.js with Express
- **Language**: TypeScript with ESM modules
- **Build Tool**: esbuild for server bundling, Vite for client
- **Session Management**: express-session with secure cookie configuration
- **Password Hashing**: bcrypt for credential security

### Data Storage
- **Primary Database**: Supabase (PostgreSQL-based)
- **ORM**: Drizzle ORM with PostgreSQL dialect
- **Schema Location**: `shared/schema.ts` contains all table definitions
- **Key Tables**:
  - `users`: Authentication data (id, username, hashed password, admin flag)
  - `profiles`: Rich user data (bio, skills, XP, level, passport ID, verification status)
  - `projects`: Project portfolio data

### Authentication & Authorization
- Session-based authentication using express-session
- Two-tier permission system:
  - `requireAuth`: Any authenticated user
  - `requireAdmin`: Admin users only
- Session data includes `userId` and `isAdmin` flags
- Secure cookie settings in production (httpOnly, sameSite strict, secure)

### API Structure
- RESTful endpoints under `/api/` prefix
- Authentication routes: `/api/auth/login`, `/api/auth/logout`, `/api/auth/session`
- Resource routes: `/api/profiles`, `/api/projects`, `/api/metrics`
- Admin routes protected by middleware

### Project Structure
```
├── client/           # React frontend
│   ├── src/
│   │   ├── components/ui/  # shadcn components
│   │   ├── pages/          # Route components
│   │   ├── lib/            # Utilities and auth context
│   │   └── hooks/          # Custom React hooks
├── server/           # Express backend
│   ├── routes.ts     # API route definitions
│   ├── storage.ts    # Database abstraction layer
│   └── supabase.ts   # Supabase client setup
├── shared/           # Shared code between client/server
│   └── schema.ts     # Drizzle schema + Zod validation
└── attached_assets/  # Static assets and brand documentation
```

## External Dependencies

### Database
- **Supabase**: Cloud PostgreSQL database
  - Requires `SUPABASE_URL` and `SUPABASE_ANON_KEY` environment variables
  - Used for all persistent data storage

### Environment Variables Required
- `DATABASE_URL`: PostgreSQL connection string (for Drizzle migrations)
- `SUPABASE_URL`: Supabase project URL
- `SUPABASE_ANON_KEY`: Supabase anonymous/public key
- `SESSION_SECRET`: Required in production for session security

### Key npm Dependencies
- `@supabase/supabase-js`: Supabase client SDK
- `drizzle-orm` + `drizzle-kit`: Database ORM and migrations
- `@tanstack/react-query`: Server state management
- `framer-motion`: Animation library
- `recharts`: Charting library
- Full shadcn/ui component set via Radix UI primitives

### Development Tools
- Vite development server with HMR
- Replit-specific plugins for development (cartographer, dev-banner, error overlay)
- TypeScript with strict mode enabled

## AeThex OS as Landing Experience

### Root Route Architecture
The site boots directly into AeThex OS at the root route (`/`). Users experience a browser-based desktop environment rather than a traditional landing page.

**Key Desktop Apps:**
- **Network Neighborhood** - Directory of founding architects + Foundry recruitment slots
- **Mission.txt** - AeThex manifesto and vision
- **The Foundry** - Links to aethex.studio bootcamp
- **Dev Tools** - Developer documentation and resources
- **System Status** - Live metrics and uptime monitoring
- **My Computer** - Passport/login and profile management

**Start Menu Features:**
- Quick access to all apps
- Clearance switch (Foundation vs Corp themes)
- Social links (Twitter, Discord, GitHub)
- Admin access for authenticated users

**Route Structure:**
- `/` - AeThex OS desktop (main landing)
- `/home` - Legacy landing page content
- `/admin/*` - Admin dashboard routes
- `/login` - Authentication page
- `/network/:slug` - Individual architect profiles

### Directory API
The `/api/directory/architects` endpoint returns only users with leadership roles (`oversee`, `admin`) - the founding team members.

## Multi-Platform Strategy (Q3 2025 Roadmap)

### Current State: Web-First
The AeThex OS (root route `/`) is the primary web application. The codebase has been prepared for future multi-platform deployment with abstraction layers.

### Platform Abstraction Layer
Located in `client/src/lib/`:
- **`platform.ts`**: Detects runtime environment (web, desktop, mobile) and provides platform-specific configuration
- **`storage.ts`**: Abstract storage adapter that uses localStorage for web and can use secure storage (keychain) for desktop/mobile
- **`api.ts`**: Centralized API request layer with configurable base URLs for different deployment contexts

### Future: Flutter Desktop App (Q3 2025)
**Why Flutter over Tauri/Electron:**
1. **Custom Rendering**: Skia/Impeller engine draws every pixel - perfect for the cyberpunk/Aegis Terminal aesthetic
2. **Cross-Platform Code Sharing**: Same codebase for iOS, Android, Windows, macOS
3. **Native Performance**: 60/120 FPS custom animations without browser overhead
4. **Passport Use Case**: Ideal for secure "Wallet/Authenticator" style apps

**Migration Path:**
1. Web remains the primary platform until revenue milestone ($50k+)
2. Flutter app will consume the same backend API (hosted on aethex.network)
3. Desktop builds will use secure storage for Supabase tokens
4. Mobile app serves as "Aegis Companion" - authenticator/passport viewer, not game client

### Environment Configuration
For desktop/mobile builds, set:
- `VITE_API_BASE_URL`: Points to production API (https://aethex.network)
- Platform detection automatically adjusts storage and API handling