Initial Ralph scaffold

docs/architecture.md

@@ -0,0 +1,33 @@
+# Architecture
+
+## Application Type
+
+**web**
+
+The application is explicitly described as a 'self-hosted web application' with a React or Vue SPA frontend and calendar week view interface, accessed via browser rather than native desktop or mobile apps.
+
+## Interface Types
+
+- rest_api
+- websocket
+
+REST API is required for external integrations (iOS Shortcuts, CLI scripts, browser extensions, capture endpoint). WebSocket enables real-time updates for automatic task rescheduling when calendar conflicts arise and notifications for displaced tasks without page refresh.
+
+## Persistence
+
+**local_db**
+
+Designed for self-hosted deployment with SQLite or PostgreSQL options specified. While PostgreSQL could be remote_db, the self-hosted context and SQLite option indicate local database persistence on the same infrastructure where the app runs.
+
+## Deployment
+
+**self_hosted**
+
+Explicitly stated as 'self-hosted' with containerized Docker Compose deployment for user-managed infrastructure, not cloud platforms or app stores. Users deploy and maintain on their own servers.
+
+## Suggested Tech Stack
+
+- **Language**: TypeScript
+- **Framework**: Node.js (NestJS backend) + React (Vite frontend) + PostgreSQL
+
+TypeScript provides type safety across full stack for complex scheduling logic and GTD workflows. NestJS offers robust REST API structure, dependency injection for external integrations (CalDAV, ConnectWise, IMAP, Microsoft Graph), scheduled jobs for recurring reviews, and WebSocket support. React with a calendar library (FullCalendar or react-big-calendar) handles the interactive drag-drop week view. PostgreSQL over SQLite for better concurrency with multiple capture sources and complex scheduling queries. Docker Compose orchestrates backend, database, and frontend nginx container for simple self-hosted deployment.