Mafl

Mafl is a lightweight, self‑hosted personal dashboard that exposes a rich set of APIs for building custom widgets and services. From a technical standpoint it is a single‑page application (SPA) backed by an Express/Node.js API that reads its configuration from YAML files stored in a mounted volume. The front‑end uses React with Vite for hot module replacement, while the back‑end leverages TypeScript for type safety and a minimal set of dependencies to keep the image size under 200 MB. The architecture is intentionally modular: each “card” on the dashboard is a self‑contained component that can fetch data from any third‑party endpoint through the server, ensuring privacy and eliminating CORS issues.

Key Features

• Privacy‑first: All external API calls are routed through the backend, preventing client‑side exposure of API keys.
• Real‑time widgets: WebSocket support via Socket.io allows cards to push updates without polling.
• Multi‑language and theming: Internationalization (i18n) is handled by react-i18next, and theme data is stored in JSON files that can be swapped at runtime.
• Extensible card system: Developers can add new cards by creating a React component and registering it in config.yml. The API also exposes CRUD endpoints for dynamic service lists.
• PWA support: Service workers and manifest files are pre‑configured, enabling installation on mobile and desktop.

Technical Stack

Core Capabilities

• REST API: /api/services, /api/cards for CRUD operations; supports pagination and filtering.
• WebSocket: /ws endpoint used by cards for live data feeds (e.g., weather, stock prices).
• Plugin hooks: onRequest and onResponse middleware can be added to the Express app for custom authentication or logging.
• CLI utilities: mafl-cli (bundled) can generate boilerplate cards, validate YAML, and deploy Docker images.

Deployment & Infrastructure

Mafl ships with a ready‑to‑run Docker image (hywax/mafl) that exposes port 3000. The only mandatory host configuration is a writable volume for /app/data, where all YAML configs and optional SQLite DB reside. For high‑availability, a reverse proxy (NGINX/Traefik) can be used to add HTTPS termination and load balancing. The application is stateless aside from the config volume, making it horizontally scalable by running multiple instances behind a load balancer and sharing the same persistent storage via NFS or cloud block storage.

Integration & Extensibility

• API integration: Any external service can be consumed by writing a small wrapper component that uses the backend’s /api/proxy endpoint.
• Webhooks: The back‑end exposes a /webhook/:id route that can be registered with third‑party services to trigger card updates.
• Theme & icon libraries: Supports Font Awesome, Material Icons, and custom SVG sets; themes are JSON‑based and can be overridden per user session.
• Developer SDK: A lightweight npm package (mafl-sdk) provides typed helpers for interacting with the API, handling authentication tokens, and subscribing to WebSocket events.

Developer Experience

• Configuration: All settings are in plain YAML (config.yml) – no JSON, no complex schema definitions. The README contains examples for grouping, tagging, and multi‑language setup.
• Documentation: Comprehensive docs are hosted at https://mafl.hywax.space, including API reference, component guidelines, and contribution workflow.
• Community: Active GitHub issues, a Discord channel for quick support, and a showcase page where developers publish custom cards.
• Licensing: MIT license ensures no copyleft constraints, making it safe for commercial use.

Use Cases

Advantages Over Alternatives

• Zero‑CORS, privacy by design – unlike client‑side dashboards that expose API keys.