How maelvls/foncia works
Project type and purpose
• This is a Go-based, monolithic CLI application with an optional long-running server mode.
• It wraps calls to an external GraphQL API (the Foncia property management API) to fetch “missionIncidents” and “missionRepairs,” persists results in a local SQLite database, provides a “list” command, and, in “serve” mode, exposes an HTTP API and hooks in notifications (ntfy.sh and optional SMTP) for new items.
Main components
A. Entry point / CLI
• main.go
• cmd_list.go (implements “foncia list”)
• sync_db_with_api.go (implements “foncia sync”)
• http_server.go (implements “foncia serve” HTTP endpoints)
• smtp_server.go (implements embedded SMTP notifications)
B. Business-logic packages
• api/ – the GraphQL client and mocks (api/api.go, api/mock)
• db/ – SQLite wrapper, schema setup, read/write operations
• logutil/ – structured logging helper
• undent/ – utility to normalize email templates
C. Data store
• Persistent SQLite file (mounted into container as foncia.sqlite)
D. External services
• Foncia GraphQL API (external HTTP endpoint)
• ntfy.sh notification service (external HTTP endpoint)
• Optional SMTP recipient (for email alerts)
Relationships and data flows
1. CLI “list”
– User invokes foncia list → calls api.Client → fetches missions from GraphQL → prints to stdout
2. DB synchronization
– CLI “sync” or background ticker in “serve” → api.Client → fetch new missions → db.Store → SQLite file
3. Server mode (“serve”)
– Starts HTTP server (http_server.go)
• HTTP endpoints read from db package → return JSON or HTML (using undent for templates)
– Starts background sync loop (reuses sync_db_with_api)
– On new mission entries → send notifications:
• ntfy.sh (HTTP POST)
• or smtp_server (renders .eml via undent, sends via Go SMTP client)
4. Logging
– All components import logutil for uniform structured logs
Architectural patterns and design principles
• Layered architecture:
• Presentation layer (CLI + HTTP handlers)
• Service layer (sync logic, notification dispatcher)
• Data layer (db package)
• Dependency inversion for external API (api/mock for tests)
• Single binary, modular packages for separation of concerns
Technologies and frameworks
• Go modules (go.mod/go.sum)
• net/http for HTTP server and client
• text/template (undent) for email/HTML templating
• SQLite via the database/sql standard library
• ntfy.sh HTTP API for push notifications
• Built & deployed with ko + Alpine container
Deployment overlay (optional)
• Docker container running the foncia binary
• Volume mounts to host file system:
• /foncia.sqlite, /invoices, /foncia-header.html
• Port mapping: host:8080 → container:8080
• Environment variables: FONCIA_USERNAME/PASSWORD, NTFY_TOPIC, BASEPATH, BASEURL