148 lines
4.6 KiB
Markdown
148 lines
4.6 KiB
Markdown
# 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:
|
|
```bash
|
|
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
|
|
|
|
**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
|