See PROJECT.md for full architecture. This is a Val.town service providing a temporary inbox for content before Obsidian vault processing.

• Platform: Val.town (Deno serverless)
• Stack: TypeScript, Hono, SQLite, Blob storage
• Purpose: Buffer layer between input sources (email/HTTP) and Obsidian clients
• Current State: Core internals focused, client integration TBD

1. Consult PROJECT.md first for architecture and data flow
2. Consult .cursor/rules/townie.mdc for Val.town platform specifics
3. Keep it simple - this is a buffer service, not a full application
4. Manual testing only - use Val.town web interface

Schema Changes:

• Update inboxRecordSchema in InboxService.ts
• Change SQLite table name (append _2, _3, etc.) - don't use ALTER TABLE
• Update handlers if record structure changes

Adding Endpoints:

• Modify httpHandler.ts (Hono app)
• Add bearer auth middleware to protected routes
• Return proper status codes (200/201/400/401/404/500)

Modifying Processing Logic:

• Email processing → emailHandler.ts
• HTTP processing → httpHandler.ts
• Keep services (InboxService, AttachmentService) as pure data operations

• No external services - use Val.town stdlib (sqlite, blob, email)
• No binary files in project - only text files allowed
• Environment variables - never hardcode secrets, use Deno.env.get()
• Val.town quirks - redirects need manual Response, not Response.redirect()
• Imports - always use https://esm.sh for npm packages

• TypeScript with explicit types on public interfaces
• Functional style preferred over classes
• Keep functions small and focused
• Export const objects for services (e.g., InboxService, AttachmentService)
• Avoid try-catch unless you have a clear local resolution

• Let errors bubble up with full context
• Don't catch just to log and re-throw
• Use Zod validation for input schemas
• Return descriptive error messages in HTTP responses

Test manually via Val.town web interface:

• Email trigger: send test emails from allowlisted addresses
• HTTP API: use curl/Postman with bearer token
• Focus on edge cases: malformed input, auth failures, missing data

When suggesting improvements, be aware of known TODOs:

• Error handling and retry logic currently not implemented
• Client architecture still being finalized
• Consider push notifications vs polling for clients

Core files you'll modify most:

• InboxService.ts - data persistence layer
• emailHandler.ts - email input processing
• httpHandler.ts - HTTP API endpoints
• auth.ts - authentication logic
• AttachmentService.ts - blob storage operations

See PROJECT.md for full file reference and component descriptions.

This codebase runs on Val.town, which means:

• Deno runtime (not Node.js)
• Serverless execution model
• Built-in SQLite and blob storage
• Email sending/receiving capabilities
• No filesystem access (use blob storage or SQLite)
• All dependencies via HTTPS imports

Refer to .cursor/rules/townie.mdc for comprehensive Val.town development guidelines including standard library usage, common gotchas, and best practices.