Fresh 2.0 Backend Development with MongoDB
Development guidelines for working with the vhybZ Deno/Fresh backend - an AI-powered platform for building interactive digital artifacts through natural language conversations.
CRITICAL: DIARY.md Workflow
**ALWAYS follow this workflow:**
1. **On startup**: Read `DIARY.md` first to understand project history and recent changes
2. **Before making changes**: Review relevant diary entries
3. **After every change**: Update `DIARY.md` with a timestamped entry including:
- Change type (feature, fix, refactor, docs, etc.)
- Description of what changed
- Rationale for the change
- Files modified
This ensures project continuity and context preservation across sessions.
Project Architecture
Core Technologies
**Runtime**: Deno with JSR package management**Framework**: Fresh 2.0 (file-based routing)**UI**: Preact with Tailwind CSS**Database**: MongoDB with Zod validation**Auth**: Google OAuth 2.0 with session cookiesMulti-Client Architecture
This backend serves multiple client applications:
**Backend API** (this repo): Deno/Fresh backend at `github.com/vhybzOS/deno-vhybZ`**Generation Library**: Core AI/LLM logic at `github.com/vhybzOS/vhybZ`**Web Frontend**: React app at vhybz.com (`github.com/vhybzOS/web-vhybZ`)**Mobile App**: React Native app (`github.com/vhybzOS/RN-vhybZ`)**Artifact Hosting**: Custom subdomains at `username.vhybz.com/artifact-name`Application Structure
**main.ts**: Core application with OAuth routes and middleware**dev.ts**: Development server with Tailwind plugin**database.ts**: MongoDB operations with Zod schemas**utils.ts**: Shared state interface and Fresh utilities**routes/**: File-based routing (Fresh convention)**islands/**: Interactive Preact components (Fresh islands)**components/**: Server-side Preact componentsProduct Flow (Backend's Role)
1. Users authenticate via backend Google OAuth
2. Frontend imports vhybZ library for ChatGPT-like interface and LLM calls
3. vhybZ library generates interactive HTML artifacts with real-time preview
4. Backend stores artifacts sent by frontend
5. Backend serves final artifacts on custom URLs for public sharing
**Architecture Separation:**
**Backend (This Repo)**: Data store, authentication, public hosting, analytics**vhybZ Library**: LLM interactions, HTML generation, real-time preview logic**Frontend Clients**: UI layer, imports vhybZ library for functionalityDevelopment Environment Separation
Backend (Root Directory) - Use Deno ONLY
**Commands**: Use `deno task` commands only**Dependencies**: JSR imports in deno.json**Runtime**: Deno with Fresh framework**Never use npm commands** in root directoryFrontend (web-vhybZ/) - Use Node.js ONLY
**Commands**: Use standard `npm` commands**Dependencies**: npm packages in package.json**Runtime**: Node.js with React Router 7**Never use deno commands** in web-vhybZ directoryDevelopment Commands
Core Development (Root Directory)
```bash
deno task dev # Start development server (builds React + runs Deno backend)
deno task dev:react # Run React app in development mode only
deno task build # Build for production
deno task start # Run production server
deno task check # Run all checks (format, lint, type checking)
deno task update # Update Fresh framework
```
Frontend Development (web-vhybZ/)
```bash
npm run dev # Start React dev server
npm run build # Build React app
npm run lint # Lint React code
```
Quality Assurance
**Before committing changes, ALWAYS run:**
```bash
deno task check # Validates formatting, linting, and type checking
```
Key Architectural Patterns
Authentication Flow
Google OAuth integration in `main.ts` with PKCE flowSession management via HTTP-only cookies`sessionMiddleware` and `requireAuth` middleware for route protectionUser creation/lookup in MongoDB via `db.findOrCreateUser()`Database Operations
Singleton database instance exported as `db`Zod schemas for type safety and validation (`UserSchema`, `AppSchema`)Environment-based MongoDB configuration with defaultsGraceful shutdown handling for database connectionsState Management
Fresh's built-in state system via `createDefine<State>()`Session state attached to request contextIslands use Preact signals for client-side reactivityEnvironment Variables
Required environment variables:
```bash
MONGODB_URI # Defaults to local MongoDB
MONGODB_DB_NAME # Defaults to "vhybZ"
GOOGLE_CLIENT_ID # For OAuth
GOOGLE_CLIENT_SECRET # For OAuth
```
Current Implementation Status
✅ Basic auth, user management, and app CRUD❌ Conversation and artifact storage APIs❌ Public subdomain hosting and artifact rendering❌ Real-time collaboration and versioning❌ Asset management and content moderationAdditional Resources
**PRD.md**: Comprehensive feature requirements**AGENTS.md**: Detailed system architecture specificationsConstraints
Always respect the runtime separation: Deno for backend, Node.js for frontendNever skip the DIARY.md update workflowAlways run `deno task check` before committingFollow Fresh 2.0 file-based routing conventionsUse Zod schemas for all database operations