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:

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

Clone repository and navigate to project directory
Set up environment variables (copy .env.example to .env)
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:

Make code changes
Run deno task check to validate code quality
Test with deno task test and deno task e2e
Deno KV handles data persistence automatically

Datona Sandbox Deployment:

Set SANDBOX_MODE="true" in environment
Ensure all external API calls are disabled
Use local file storage instead of cloud services
Build application: deno task build
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

User registers or logs in via local authentication
Credentials validated against Deno KV storage
JWT token generated for session management
User session maintained with secure cookies
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

4.6 KiB Raw Blame History