# maelvls/foncia architecture

> Architecture diagram of the GitHub repository maelvls/foncia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maelvls/foncia
- Repository: https://github.com/maelvls/foncia

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / User Layer
    subgraph "CLI / User Layer"
        CLI["Foncia CLI\n(main.go)"]:::internal
        List["List Command\n(cmd_list.go)"]:::internal
        Sync["Sync Command\n(sync_db_with_api.go)"]:::internal
    end

    %% Server Layer
    subgraph "Server Layer"
        HttpS["HTTP Server\n(http_server.go)"]:::internal
        SmtpS["SMTP Messenger\n(smtp_server.go)"]:::internal
    end

    %% Business Logic Packages
    subgraph "Business Logic Packages"
        Api["GraphQL Client\n(api/api.go)"]:::internal
        Mock["API Mocks\n(api/mock/mock.go)"]:::internal
        Db["DB Wrapper\n(db/db.go)"]:::internal
        Log["Logging Util\n(logutil/logutil.go)"]:::internal
        Und["Template Util\n(undent/undent.go)"]:::internal
    end

    %% Storage
    SQLite["SQLite File\n(foncia.sqlite)"]:::db
    EmailFull["email-full.eml"]:::storage
    EmailSimple["email-simplified.eml"]:::storage

    %% External Services
    subgraph External
        GraphQL["Foncia GraphQL API"]:::external
        Ntfy["ntfy.sh Service"]:::messaging
        SMTPEx["SMTP Recipient"]:::messaging
    end

    %% Relationships
    CLI -->|invokes| List
    CLI -->|invokes| Sync
    List -->|uses| Api
    Api -->|HTTP| GraphQL
    Sync -->|fetch/store| Api
    Sync -->|writes| Db
    Db -->|persists| SQLite
    HttpS -->|reads/writes| Db
    HttpS -->|templates| Und
    Sync -->|on new| Ntfy
    Sync -->|on new| SmtpS
    SmtpS -->|loads template| EmailFull
    SmtpS -->|loads template| EmailSimple
    SmtpS -->|SMTP| SMTPEx

    %% Logging
    CLI -->|logs to| Log
    HttpS -->|logs to| Log
    Sync -->|logs to| Log
    SmtpS -->|logs to| Log
    Api -->|logs to| Log
    Db -->|logs to| Log

    %% Click Events
    click CLI "https://github.com/maelvls/foncia/blob/main/main.go"
    click List "https://github.com/maelvls/foncia/blob/main/cmd_list.go"
    click Sync "https://github.com/maelvls/foncia/blob/main/sync_db_with_api.go"
    click HttpS "https://github.com/maelvls/foncia/blob/main/http_server.go"
    click SmtpS "https://github.com/maelvls/foncia/blob/main/smtp_server.go"
    click Api "https://github.com/maelvls/foncia/blob/main/api/api.go"
    click Mock "https://github.com/maelvls/foncia/blob/main/api/mock/mock.go"
    click Db "https://github.com/maelvls/foncia/blob/main/db/db.go"
    click Log "https://github.com/maelvls/foncia/blob/main/logutil/logutil.go"
    click Und "https://github.com/maelvls/foncia/blob/main/undent/undent.go"
    click EmailFull "https://github.com/maelvls/foncia/blob/main/email-full.eml"
    click EmailSimple "https://github.com/maelvls/foncia/blob/main/email-simplified.eml"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#2b6cb0,color:#1a365d
    classDef db fill:#c6f6d5,stroke:#276749,color:#22543d,shape:cylinder
    classDef external stroke-dasharray: 5 5,fill:#f0f0f0,stroke:#718096
    classDef messaging fill:#fed7aa,stroke:#dd6b20,color:#7b341e,shape:cylinder
    classDef storage fill:#e2e8f0,stroke:#4a5568,color:#2d3748,shape:cylinder
```
