# vito-93/ffiiitc architecture

> Architecture diagram of the GitHub repository vito-93/ffiiitc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vito-93/ffiiitc
- Repository: https://github.com/vito-93/ffiiitc

## Overview

ffiiitc is a webhook-driven FireFly III transaction classifier. FireFly sends newly created transaction details to the service; the service classifies each description and asks FireFly to update its category. On startup, it loads a saved model or fetches transactions and trains one; a separate endpoint can force retraining, optionally over a date range. The graph also shows configuration, HTTP routing, and the FireFly API boundary. The README documents the webhook and retraining capabilities; source excerpts show the call paths. The model file is referenced in code but is runtime state, not a repository file.

Main entry points: [`internal/handlers/handler.go`](https://github.com/vito-93/ffiiitc/blob/main/internal/handlers/handler.go) (Webhook handlers), [`main.go`](https://github.com/vito-93/ffiiitc/blob/main/main.go) (Startup wiring), [`internal/firefly/firefly.go`](https://github.com/vito-93/ffiiitc/blob/main/internal/firefly/firefly.go) (FireFly API client), [`internal/router/router.go`](https://github.com/vito-93/ffiiitc/blob/main/internal/router/router.go) (HTTP router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service entry"]
  node_main["Startup wiring<br/>[main.go]"]
  node_config["Environment config<br/>[config.go]"]
end

subgraph group_http["HTTP endpoints"]
  node_router["HTTP router<br/>[router.go]"]
  node_handlers["Webhook handlers<br/>[handler.go]"]
end

subgraph group_classification["Classification"]
  node_classifier["Bayesian classifier<br/>[classifier.go]"]
  node_model["Saved model"]
end

subgraph group_firefly["FireFly integration"]
  node_client["FireFly API client<br/>[firefly.go]"]
end

node_firefly_user(("FireFly user"))
node_webhook(("Transaction webhook"))
node_firefly_api["FireFly API"]

node_firefly_user -->|"triggers"| node_webhook
node_webhook -->|"posts webhook"| node_router
node_main -->|"loads config"| node_config
node_main -->|"creates client"| node_client
node_main -->|"loads or trains"| node_classifier
node_main -->|"loads or saves"| node_model
node_main -->|"starts server"| node_router
node_main -->|"registers routes"| node_handlers
node_router -->|"dispatches requests"| node_handlers
node_handlers -->|"classifies descriptions"| node_classifier
node_handlers -->|"requests dataset"| node_client
node_handlers -->|"updates category"| node_client
node_handlers -->|"trains model"| node_classifier
node_handlers -->|"saves model"| node_model
node_client -->|"reads transactions"| node_firefly_api
node_client -->|"updates transaction"| node_firefly_api

click node_main "https://github.com/vito-93/ffiiitc/blob/main/main.go"
click node_config "https://github.com/vito-93/ffiiitc/blob/main/internal/config/config.go"
click node_router "https://github.com/vito-93/ffiiitc/blob/main/internal/router/router.go"
click node_handlers "https://github.com/vito-93/ffiiitc/blob/main/internal/handlers/handler.go"
click node_classifier "https://github.com/vito-93/ffiiitc/blob/main/internal/classifier/classifier.go"
click node_client "https://github.com/vito-93/ffiiitc/blob/main/internal/firefly/firefly.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_firefly_user toneBlue
class node_router,node_handlers toneAmber
class node_classifier,node_model,node_webhook,node_firefly_api toneMint
class node_client toneRose
```

## Components

### Service entry

- [Startup wiring](https://github.com/vito-93/ffiiitc/blob/main/main.go): `main.go`
- [Environment config](https://github.com/vito-93/ffiiitc/blob/main/internal/config/config.go): `internal/config/config.go`

### HTTP endpoints

- [HTTP router](https://github.com/vito-93/ffiiitc/blob/main/internal/router/router.go): `internal/router/router.go`
- [Webhook handlers](https://github.com/vito-93/ffiiitc/blob/main/internal/handlers/handler.go): `internal/handlers/handler.go`

### Classification

- [Bayesian classifier](https://github.com/vito-93/ffiiitc/blob/main/internal/classifier/classifier.go): `internal/classifier/classifier.go`
- **Saved model**

### FireFly integration

- [FireFly API client](https://github.com/vito-93/ffiiitc/blob/main/internal/firefly/firefly.go): `internal/firefly/firefly.go`

### Other components

- **FireFly user**
- **Transaction webhook**
- **FireFly API**

## Connections

- FireFly user → Transaction webhook: triggers (evidence: `README.md`)
- Transaction webhook → HTTP router: posts webhook (evidence: `README.md`)
- Startup wiring → Environment config: loads config (evidence: `main.go`)
- Startup wiring → FireFly API client: creates client (evidence: `main.go`)
- Startup wiring → Bayesian classifier: loads or trains (evidence: `main.go`)
- Startup wiring → Saved model: loads or saves (evidence: `main.go`)
- Startup wiring → HTTP router: starts server (evidence: `main.go`)
- Startup wiring → Webhook handlers: registers routes (evidence: `main.go`)
- HTTP router → Webhook handlers: dispatches requests
- Webhook handlers → Bayesian classifier: classifies descriptions (evidence: `internal/handlers/handler.go`)
- Webhook handlers → FireFly API client: requests dataset (evidence: `internal/handlers/handler.go`)
- Webhook handlers → FireFly API client: updates category (evidence: `internal/handlers/handler.go`)
- Webhook handlers → Bayesian classifier: trains model (evidence: `internal/handlers/handler.go`)
- Webhook handlers → Saved model: saves model (evidence: `internal/handlers/handler.go`)
- FireFly API client → FireFly API: reads transactions (evidence: `internal/firefly/firefly.go`)
- FireFly API client → FireFly API: updates transaction (evidence: `internal/firefly/firefly.go`)
