integratedhub/AGENTS.md

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:

# 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 -LO https://github.com/denoland/deno/releases/latest/download/deno-x86_64-unknown-linux-gnu.zip
   unzip deno-x86_64-unknown-linux-gnu.zip
   sudo mv deno /usr/local/bin/
   rm deno-x86_64-unknown-linux-gnu.zip
   

2. Clone repository and navigate to project directory
3. Set up environment variables (copy .env.example to .env)
4. 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 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
5. File-Level Validation: When coding, ensure compliance by running the following commands on the specific file being modified (replace with your file path):

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