# 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_