Christmas Community

Christmas Community is a lightweight, self‑hosted web application written in JavaScript that enables families or small groups to collaboratively manage gift lists and avoid duplicate purchases. At its core, the app exposes a REST‑style API backed by PouchDB, which can run either as an embedded local database or against any CouchDB‑compatible server. The UI is a single‑page application that consumes this API, rendering lists in either “box” or “table” mode based on environment variables. From a developer’s standpoint, the project is intentionally minimalistic: it relies on Node.js for the runtime, Express‑like middleware for routing, and a set of environment variables to drive configuration. This design choice keeps the codebase approachable while still offering enough hooks for advanced customization.

Architecture

The stack is built around three core technologies:

• Node.js (v18+) – the runtime that powers both the API and the static asset server.
• PouchDB – a JavaScript database that mirrors CouchDB’s document model. It can be stored locally in the ./data directory or pointed to a remote CouchDB instance via DB_PREFIX.
• React/Vue‑style SPA – the front‑end is bundled with Webpack (or a similar bundler) and served from the public/ directory. It communicates with the API over HTTP, using JSON payloads.

The application exposes a few key endpoints: /api/lists, /api/items, and /api/users. These are protected by a simple cookie‑based session system whose secret is derived from the SECRET environment variable. For developers wanting to embed Christmas Community in a larger ecosystem, the API surface can be extended by adding middleware or custom routes without touching the core logic.

Core Capabilities

• Dynamic List Modes – Toggle between a “box” view (default) and a “table” view via the TABLE flag.
• Single‑List Mode – When SINGLE_LIST=true, only the admin’s list is visible, useful for events like weddings.
• CouchDB Compatibility – By exposing the internal PouchDB instance through DB_EXPOSE_PORT, developers can debug via Fauxton or integrate with external tools.
• Proxy Support – The PROXY_SERVER variable allows the app to forward item data requests, enabling integration with external e‑commerce APIs.
• Header Size Configuration – NODE_OPTIONS can be overridden to adjust the maximum HTTP header size, accommodating sites that send large headers (e.g., Walmart).

Deployment & Infrastructure

Christmas Community ships as a Docker image (wingysam/christmas-community), making containerized deployment straightforward. A typical Compose file mounts a persistent volume (./data) for the database, exposes port 80, and sets environment variables to enable desired features. The image is lightweight (under 200 MB) and has no external dependencies beyond Node.js, which Docker provides. For non‑Docker environments, the repo can be cloned and run with npm start, but Docker remains the recommended path for production due to its isolation and ease of scaling.

Integration & Extensibility

Because the app is built on top of PouchDB, developers can tap into CouchDB’s replication API to sync data across multiple instances. The exposed API endpoints are intentionally generic, allowing third‑party services (e.g., a custom frontend or a bot) to read/write lists and items. Webhooks can be implemented by wrapping the existing routes with an event emitter; for example, a POST /api/items could trigger a Slack notification via the Discord integration already present. The configuration system is environment‑variable driven, making it trivial to extend or override behavior in CI/CD pipelines.

Developer Experience

The project’s documentation is concise yet complete: a single README.md covers purpose, configuration, and deployment. Environment variables are self‑documenting with comments in the sample .env file. The codebase follows standard JavaScript conventions, and unit tests (if any) can be added without breaking the existing API. Community support is bolstered by an active Discord server, where contributors can discuss feature requests or report bugs. Licensing is permissive (MIT), encouraging reuse and modification without legal overhead.

Use Cases

• Family Gift Lists – A small team can host a shared list, preventing duplicate gifts.
• Event Planning – Wedding or birthday planners can enable SINGLE_LIST to centralize wish lists.
• E‑commerce Integration – By configuring PROXY_SERVER, the app can fetch product details from external sites, turning it into a lightweight price‑tracking tool.
• Custom Frontends – Developers can replace the bundled SPA with a React or Vue application, consuming the same API.
• Internal Company Tool – Small companies can use it for office gift exchanges or holiday potlucks, leveraging CouchDB replication to sync across locations.

Advantages

• Simplicity – Minimal dependencies and a clear configuration model make onboarding fast.
• Flexibility – PouchDB’s dual local/remote storage and CouchDB‑compatibility allow a range of deployment scenarios.
• Performance – Node.js and PouchDB provide low‑latency CRUD operations, suitable for the modest load typical of family use.
• Licensing – MIT license removes barriers to modification and redistribution, unlike proprietary alternatives.
• Community & Support – A dedicated Discord channel ensures quick help and fosters a collaborative ecosystem.

Overall,