Wallos

Wallos is a self‑hosted, open‑source web application focused on subscription tracking and personal finance management. From a developer’s perspective it functions as a REST‑ful microservice that exposes CRUD endpoints for subscriptions, categories, and notifications while also providing a GraphQL‑style schema through its API documentation. The core business logic is written in Node.js (TypeScript), leveraging the Express framework for routing and middleware. Data persistence is handled by PostgreSQL, accessed via a lightweight ORM (TypeORM or Prisma), which ensures strong typing, migrations, and support for complex queries such as currency conversion aggregation.

Architecture & Technical Stack

• Language: TypeScript (Node.js 18+)
• Frameworks: Express for HTTP, Passport/OIDC for authentication
• Database: PostgreSQL (supports foreign keys, JSONB, and full‑text search for logo lookup)
• External Integrations: Fixer.io API for real‑time exchange rates, multiple notification backends (SMTP, Discord, Telegram, Pushover, Gotify, Webhook), and optional AI engines (ChatGPT/Gemini/Ollama) via OpenAI‑compatible APIs
• Containerization: Official Docker images (bellamy/wallos) and a docker‑compose.yml template that includes the database, Redis (for caching), and optional reverse proxy
• Scalability: Stateless API servers behind a load balancer; PostgreSQL can be scaled read‑only replicas, while Redis handles rate limiting and caching of exchange rates

Core Capabilities & Developer APIs

• Subscription CRUD: Create, read, update, delete subscriptions with fields such as name, amount, frequency, next due date, and optional logo URL
• Category Management: Hierarchical categories with customizable display order and color codes
• Multi‑Currency Support: Store amounts in any currency; API automatically fetches latest rates from Fixer and caches them
• Notification System: Configure multiple channels per user; webhooks can be used to trigger external workflows (e.g., Slack alerts, custom scripts)
• AI Recommendations: Endpoint /api/v1/ai/recommend accepts user context and returns subscription optimization suggestions
• OIDC/OAuth: Supports external identity providers; developers can integrate with Keycloak, Auth0, or custom OIDC servers
• Extensibility Hooks: Webhooks for events (subscription created/updated), and a plugin interface via JSON‑configurable modules that can add new fields or modify the UI

Deployment & Infrastructure

Wallos is designed for bare‑metal and Docker deployments. The Docker image includes a non‑root user, uses multi‑stage builds for minimal footprint, and exposes health checks (/healthz). For production, a typical setup involves:

1. PostgreSQL – primary database with SSL enabled
2. Redis – optional for caching exchange rates and session storage
3. NGINX/Traefik – reverse proxy with HTTPS termination and rate limiting
4. Docker‑Compose – orchestrates the stack; can be upgraded via docker compose pull followed by a graceful restart

The application is horizontally scalable: multiple API containers can be run behind the reverse proxy, sharing the same database and Redis instance. Continuous deployment pipelines can rebuild images from the GitHub repo and push to a private registry.

Integration & Extensibility

• Webhooks: Emit JSON payloads for events such as subscription.created or payment.overdue. Consumers can trigger external automations (e.g., Zapier, custom cron jobs).
• Plugin System: Developers can create lightweight plugins that register new API routes or UI components via a JSON schema. The core loads these at startup, allowing for feature extensions without modifying the base codebase.
• OAuth/OIDC: Seamless integration with corporate identity providers; developers can enforce MFA or SSO.
• Custom Themes: CSS variables expose theming options; developers can ship brand‑specific styles or dark mode overrides.

Developer Experience

The repository follows a clean monorepo structure with comprehensive unit and integration tests (Jest). Documentation is split into docs/ and inline comments, providing API usage examples and migration guides. Community support is active via Discord, GitHub Discussions, and a contributor‑friendly issue tracker. Licensing under AGPL‑3.0 ensures that any derived work remains open, encouraging collaborative improvements.

Use Cases

1. Personal Finance Dashboard – A developer can embed Wallos into a personal portfolio site, exposing subscription data via GraphQL to a React front‑end.
2. Enterprise Expense Tracking – Companies can host Wallos on their intranet to monitor employee subscriptions, integrating with LDAP for authentication and Slack for notifications.
3. FinTech Integration Layer – Wallos can act as a microservice that aggregates subscription data from multiple sources (e.g., Stripe, PayPal) and exposes a unified API for higher‑level analytics.
4. AI‑Driven Savings Coach – By hooking into the AI recommendation endpoint, developers can build chatbots that suggest subscription cancellations or better plans.

Advantages

• Performance: TypeScript + Express delivers low latency; PostgreSQL’s query planner handles complex aggregation efficiently.
• Flexibility: Full control over data schema, custom fields, and notification channels; no vendor lock‑in.
• Scalability: Stateless API, cacheable