131 lines
5.4 KiB
Markdown
131 lines
5.4 KiB
Markdown
# Technology Stack
|
|
|
|
**Analysis Date:** 2026-06-09
|
|
|
|
## Languages
|
|
|
|
**Primary:**
|
|
- TypeScript 5.5.x - Full stack: backend (`apps/api/src`), frontend (`apps/pwa/src`), shared types
|
|
- JavaScript - Package tooling (node-cron, vite config, drizzle config)
|
|
|
|
**Secondary:**
|
|
- CSS - Styling (imported via Vite; Schedule-X provides default theme)
|
|
- HTML - PWA manifest generation via vite-plugin-pwa
|
|
|
|
## Runtime
|
|
|
|
**Environment:**
|
|
- Node.js 22 LTS (`FROM node:22-alpine` in Dockerfile)
|
|
- Browser: ES2023 target; iOS 16.4+ (PWA home-screen install required)
|
|
|
|
**Package Manager:**
|
|
- pnpm 11.5.1
|
|
- Lockfile: `pnpm-lock.yaml` present
|
|
- Workspace: `pnpm-workspace.yaml` with `apps/*` packages
|
|
|
|
## Frameworks
|
|
|
|
**Core (Backend):**
|
|
- Hono 4.12.23 - HTTP framework with Web Standards API; `@hono/node-server` for Node.js runtime
|
|
- @hono/oidc-auth 1.8.3 - OIDC session middleware (Authelia integration; storage-less JWT cookies)
|
|
- @hono/zod-validator 0.8.0 - Request body/query validation in route handlers
|
|
|
|
**Core (Frontend):**
|
|
- React 19.x - PWA frontend with concurrent features
|
|
- Vite 8.0.16 - Build tooling (dev server with HMR, production bundler)
|
|
- vite-plugin-pwa 1.3.0 - Service worker registration, PWA manifest generation, Workbox 7 integration
|
|
|
|
**Calendar UI:**
|
|
- @schedule-x/react 4.1.0 - Calendar component wrapper
|
|
- @schedule-x/calendar 4.6.0 - Core calendar rendering
|
|
- @schedule-x/event-modal 4.6.0 - Event detail/edit modal
|
|
- @schedule-x/events-service 4.6.0 - Event data management
|
|
- @schedule-x/calendar-controls 4.6.0 - Month/week navigation
|
|
- @schedule-x/theme-default 4.6.0 - Default theme (CSS overridden by `apps/pwa/src/styles/tokens.css`)
|
|
|
|
**Client State:**
|
|
- @tanstack/react-query 5.101.0 - Server state fetching, caching, background refetch, invalidation
|
|
- zustand 5.0.14 - UI-only state (selected date range, color assignments, drawer states)
|
|
|
|
**Testing (Backend):**
|
|
- Vitest 4.1.8+ - Unit + integration test runner; config: `apps/api/vitest.config.ts` (environment: node, globals: true)
|
|
|
|
**Testing (Frontend):**
|
|
- Vitest 4.1.8+ - Unit test runner; config: `apps/pwa/vitest.config.ts` (environment: jsdom, TZ=UTC for deterministic date tests)
|
|
- @testing-library/react 16.3.0 - Component testing utilities
|
|
- @testing-library/jest-dom 6.6.3+ - Jest DOM matchers
|
|
|
|
**Build/Dev:**
|
|
- @vitejs/plugin-react 4.3.0+ - JSX transform, React Fast Refresh
|
|
|
|
## Key Dependencies
|
|
|
|
**Critical (CalDAV):**
|
|
- tsdav 2.2.2 - CalDAV client for Fastmail integration; fetches calendars (PROPFIND) and events (REPORT); handles Basic auth
|
|
- ical.js 2.2.1 - iCalendar (.ics) parsing on both backend (CalDAV responses) and frontend (event hydration); Mozilla-maintained reference implementation
|
|
- rrule 2.8.1 - Not yet declared; RRULE expansion for recurring event expansion (Phase 2 calendar view)
|
|
|
|
**Critical (Database):**
|
|
- drizzle-orm 0.45.2 - Type-safe SQL ORM; MySQL dialect targeting MariaDB; zero runtime overhead
|
|
- drizzle-kit 0.31.10 - Schema migration generator (generates SQL from `apps/api/src/db/schema.ts`)
|
|
- mysql2 3.22.4 - Native MariaDB/MySQL driver; Promises API; used by Drizzle
|
|
|
|
**Critical (Validation):**
|
|
- zod 3.25.0+ - Schema validation (event payloads, API requests)
|
|
|
|
**Supporting (Backend):**
|
|
- node-cron 4.2.1+ - Cron scheduling for CalDAV poller (5-min), outbox worker (15-sec)
|
|
- temporal-polyfill 0.3.2 - Temporal API polyfill for date/time operations (ISO 8601 handling)
|
|
|
|
**Supporting (Frontend):**
|
|
- temporal-polyfill 0.3.2 - Same Temporal polyfill; imported before Schedule-X at `apps/pwa/src/main.tsx:7`
|
|
- lucide-react 1.17.0 - Icon library
|
|
- idb 7.1.1 - IndexedDB wrapper (optional; available but not yet wired)
|
|
|
|
**Development Only:**
|
|
- @types/node 22.x - Node.js type definitions
|
|
- @types/react 19.x - React type definitions
|
|
- @types/react-dom 19.x - React DOM type definitions
|
|
- jsdom 26.1.0+ - DOM simulation for frontend tests
|
|
|
|
## Configuration
|
|
|
|
**Environment (Backend — `apps/api`):**
|
|
- `.env` - Local secrets (DB credentials, OIDC settings, encryption key); pattern in `docker-compose.yml`
|
|
- `drizzle.config.ts` - Dialect: mysql; schema path: `./src/db/schema.ts`; migrations: `./src/db/migrations`
|
|
- `tsconfig.json` - Target: ES2023; module: NodeNext; strict: true
|
|
|
|
**Environment (Frontend — `apps/pwa`):**
|
|
- `vite.config.ts` - React plugin, PWA plugin (Workbox config with navigateFallback and denylist for /callback, /api/*, /health)
|
|
- `tsconfig.json` - Target: ES2023; lib: [ES2023, DOM, DOM.Iterable]; jsx: react-jsx; strict: true
|
|
|
|
**Build (Docker):**
|
|
- Multi-stage Dockerfile (`apps/api/Dockerfile`):
|
|
- `base` - Node 22 Alpine with pnpm enabled
|
|
- `builder` - TypeScript compilation for API only
|
|
- `pwa-builder` - Vite build for PWA (produces `dist/`)
|
|
- `dev` - Development image with hot-reload via `node --watch`
|
|
- `production` - Single port (:3000) serving both API and PWA static files
|
|
|
|
## Platform Requirements
|
|
|
|
**Development:**
|
|
- Node.js 22 LTS
|
|
- pnpm 11.5.1
|
|
- Docker + Docker Compose (for local MariaDB + Redis)
|
|
- MariaDB 11 (via `docker-compose.yml`)
|
|
- Redis 7-Alpine (via `docker-compose.yml`, present but unused in Phase 1)
|
|
- Vite dev server proxy: `localhost:3000` for /api, /callback, /health
|
|
|
|
**Production:**
|
|
- Node.js 22 LTS runtime in Docker container
|
|
- Authelia OIDC provider (pre-deployed; configured via env vars)
|
|
- MariaDB 11 database
|
|
- Redis 7 (optional; reserved for Phase 4 live list sync pub/sub)
|
|
- Pangolin/Newt tunnel for secure external access (no open ports)
|
|
- Split-DNS internal domain resolution
|
|
|
|
---
|
|
|
|
*Stack analysis: 2026-06-09*
|