Our Shopping List

Our Shopping List (OSL) is a lightweight, real‑time collaborative list manager written in modern web technologies. At its core it exposes a RESTful API for CRUD operations on boards, lists and items, while the front‑end consumes this API via WebSocket for instant synchronization across clients. The application is designed to run in a containerized environment, making it trivial to deploy behind a reverse proxy or as part of a larger micro‑service stack.

Technical Stack & Architecture

• Frontend: A Vue 3 single‑page application using Vite as the build tool. State management is handled by Pinia, and real‑time updates are delivered through a Socket.io client. The UI is mobile‑first, leveraging CSS Grid and Flexbox for responsive layouts; swipe gestures are implemented with Hammer.js.
• Backend: A Node.js/Express server written in TypeScript. It hosts the REST API and a Socket.io namespace for live updates. All business logic resides in service modules, keeping the controller layer thin.
• Database: PostgreSQL is used as the primary datastore. The schema is intentionally flat—boards, lists and items are stored in separate tables with foreign keys for referential integrity. The items table includes a boolean checked, a quantity column, and a details text field. A JSONB column holds i18n metadata for future language support.
• Real‑time Sync: Socket.io broadcasts item:update, list:create and other events to all connected clients. The server emits changes immediately after persisting them, ensuring near‑zero latency for collaborative editing.

Core Capabilities & APIs

• Boards: Optional grouping of lists. When VITE_APP_SINGLEBOARD_MODE is enabled, all data is stored under a hidden default board. The CLI tool (cli.js) can migrate lists between modes.
• Lists & Items: CRUD endpoints expose full control over list metadata and item properties. Batch operations are supported via bulk update routes.
• Search & Filtering: The API accepts query parameters (search, checked) to filter items server‑side, reducing payload size for the client.
• Webhooks: An optional webhook endpoint can be configured to notify external services on item state changes. This is useful for integrating with home‑automation or notification platforms.
• PWA Skeleton: Service workers are registered to cache static assets, providing a basic offline experience. Full offline persistence is planned for future releases.

Deployment & Infrastructure

• Containerization: A docker-compose.yml bundles the app, a PostgreSQL container and an optional Redis instance for Socket.io scaling. Environment variables control all aspects of the deployment (DB credentials, singleboard mode, etc.).
• Scalability: Socket.io can be configured to use a Redis adapter, enabling horizontal scaling across multiple app instances behind a load balancer.
• Self‑Hosting Requirements: The only prerequisites are Docker, Docker Compose and a PostgreSQL instance. No external services are required, making OSL suitable for on‑premise or cloud deployments where data residency is critical.

Integration & Extensibility

• CLI Tool: The bundled Node CLI (cli.js) allows migration scripts, board creation and list re‑assignment without interacting with the UI. This is ideal for automated provisioning or bulk updates.
• Plugin Architecture: While not yet fully mature, the backend exposes hooks (onItemCreate, onListDelete) that can be overridden by custom middleware. Developers can extend functionality without modifying the core codebase.
• Internationalisation: The front‑end uses vue-i18n with JSON locale files. Adding a new language is as simple as dropping a fr.json into the locales directory and updating the build configuration.

Developer Experience

• Documentation: The README covers migration paths, environment variables and CLI usage. Inline JSDoc comments in the TypeScript source aid IDE autocompletion.
• Configuration: All major features are toggleable via environment variables, allowing developers to ship minimal builds for internal use or full-featured instances for public deployments.
• Community: The project is open‑source on GitHub, with an active issue tracker and pull request workflow. Contributors are encouraged to add i18n translations and improve PWA capabilities.

Use Cases

1. Team Collaboration: Small teams can host a private instance to manage shared shopping lists, task allocations or event planning without relying on commercial SaaS.
2. IoT Integration: The webhook system can feed into home‑automation platforms (e.g., Home Assistant) to trigger actions when items are checked.
3. Internal Tooling: Companies can embed OSL into their intranet, using the singleboard mode for department‑wide to‑do lists.
4. Educational Projects: The clean architecture and TypeScript codebase make it an excellent teaching example for full‑stack development, real‑time communication and container orchestration.

Advantages Over Alternatives

• Full Control: Self‑hosted with no vendor lock‑in, giving developers ownership of data and the ability to audit code.
• Performance: Socket.io delivers sub‑second updates, while PostgreSQL ensures ACID compliance for concurrent edits.
• Extensibility: The CLI and hook system allow rapid feature addition without touching core logic.
• Licensing: MIT license permits commercial use and modification, making it safe for enterprise deployments.

In summary, Our Shopping List is a solid, developer‑friendly foundation for any project requiring shared lists with real‑time collaboration. Its modular architecture, clear API surface and containerized deployment model make it easy to