# CyberHybridHub - Deno Fresh Web App Setup Guide

## Overview
CyberHybridHub is a modern web application built with Deno Fresh framework, utilizing Drizzle ORM for database management, TailwindCSS for styling, and designed for Datona sandbox environments.

<dependencies_and_installation>
**Package Manager**: Use Deno CLI exclusively (no npm/yarn required)

**Core Dependencies**:
- **Deno**: Latest runtime (https://deno.land/)
- **Fresh Framework**: `jsr:@fresh/core@^2.2.0`
- **Database**: Deno KV (built-in key-value storage)
- **Styling**: TailwindCSS v4.1.17
- **UI**: Preact components with signals
- **Authentication**: Local authentication system

**Database Setup**:
- Deno KV is used for Datona sandbox compatibility
- Database initialized automatically on startup
- No external database server required
- Built-in Deno KV storage handles all data persistence

**External Services**:
- **Local File Storage**: Used for blob storage in sandbox
- **In-Memory Cache**: Built-in Deno KV for caching
- No external service dependencies required for sandbox

**Environment Variables**:
Set the following environment variables before running the application:

```bash
# Server Configuration
PORT="8080"
HOSTNAME_DENO="localhost"
DEVELOPMENT="true"  # Set to "false" for production

# File Storage Paths
KV_CACHE_PATH="./data"
POSTGRES_OPTIONS="postgresql://postgres:9UMrd6hKBho4RhoyP47t@data1.cyberhybridhub.com:5432/postgres?sslmode=verify-full&connect_timeout=10&sslrootcert=./certs/root.crt"

# Datona Sandbox Specific
SANDBOX_MODE="true"
DISABLE_EXTERNAL_APIS="true"
LOCAL_DEV_MODE="true"
```

**Startup Sequence**:
1. Install Deno: `curl -fsSL https://deno.land/install.sh | sh`
2. Clone repository and navigate to project directory
4. Set up environment variables (copy `.env.example` to `.env`)
5. Start development server: `deno task dev` (Deno KV initializes automatically)

**Available Deno Tasks**:
- `deno task dev` - Start development server with Vite
- `deno task build` - Build for production
- `deno task start` - Start production server
- `deno task check` - Format, lint, and type check
- `deno task test` - Run unit tests
- `deno task e2e` - Run Playwright end-to-end tests

**Development Workflow**:
1. Make code changes
2. Run `deno task check` to validate code quality
3. Test with `deno task test` and `deno task e2e`
4. Deno KV handles data persistence automatically

**Datona Sandbox Deployment**:
1. Set `SANDBOX_MODE="true"` in environment
2. Ensure all external API calls are disabled
3. Use local file storage instead of cloud services
4. Build application: `deno task build`
5. Start production server: `deno task start`
</dependencies_and_installation>

## Architecture Overview

### Directory Structure
- `routes/` - Fresh framework route handlers and pages
- `islands/` - Interactive Preact components
- `components/` - Reusable UI components
- `db/` - Database schema and connection logic
- `services/` - Business logic and external service integrations
- `utils/` - Utility functions and helpers
- `types/` - TypeScript type definitions
- `static/` - Static assets (CSS, images, etc.)
- `drizzle/` - Database migration files

### Key Technologies
- **Fresh**: Full-stack web framework with edge-first architecture
- **Deno KV**: Built-in key-value storage for data persistence
- **TailwindCSS**: Utility-first CSS framework
- **Preact**: Fast, lightweight React alternative
- **Local Authentication**: JWT-based authentication system

### Authentication Flow
1. User registers or logs in via local authentication
2. Credentials validated against Deno KV storage
3. JWT token generated for session management
4. User session maintained with secure cookies
5. Deno KV handles user data and session persistence

## Development Guidelines

### Code Style
- Use TypeScript for all new code
- Follow Fresh framework conventions
- Utilize TailwindCSS for styling
- Implement proper error handling and logging
- Write tests for new features and functions

### Database Operations
- All data operations use Deno KV key-value storage
- No schema migrations required
- Automatic data persistence and backup
- Built-in caching and performance optimization
- Simple API for CRUD operations

### Security Considerations
- Never commit secrets or API keys
- Use environment variables for sensitive configuration
- Implement proper input validation and sanitization
- Follow OWASP security guidelines
- Use local authentication to avoid external dependencies
- Regular security audits and dependency updates