# ricardomarassato/fiap-postech-tc4-togglemaster architecture

> Architecture diagram of the GitHub repository ricardomarassato/fiap-postech-tc4-togglemaster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ricardomarassato/fiap-postech-tc4-togglemaster
- Repository: https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster

## Overview

ToggleMaster is a feature-flag platform whose primary workflow evaluates a user’s flag request, retrieves flag and targeting data, applies the targeting rule, returns a decision, and asynchronously records an analytics event. Its five services are instrumented for centralized telemetry; Grafana alerts can trigger in-cluster remediation and external incident notifications. The workflow and observability links are documented in the README; unsampled deployment wiring is shown only where that documentation supports it.

Main entry points: [`gitops/observability/otel-collector.yaml`](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/otel-collector.yaml) (OTel Collector), [`services/auth-service/handlers.go`](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/auth-service/handlers.go) (Auth API), [`gitops/observability/grafana-alerting.yaml`](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/grafana-alerting.yaml) (Grafana Alerts), [`services/evaluation-service/handlers.go`](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/evaluation-service/handlers.go) (Evaluation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Flag Platform"]
  node_evaluation["Evaluation API<br/>[handlers.go]"]
  node_evaluator["Decision Logic<br/>[evaluator.go]"]
  node_flag["Flag API<br/>[app.py]"]
  node_targeting["Targeting API<br/>[app.py]"]
  node_auth["Auth API<br/>[handlers.go]"]
  node_keygen["API Key Generation<br/>[key.go]"]
  node_analytics["Analytics Worker<br/>[app.py]"]
end

subgraph group_telemetry["Observability"]
  node_collector["OTel Collector"]
  node_prometheus[("Prometheus")]
  node_loki[("Grafana Loki")]
  node_grafana["Grafana Alerts"]
end

subgraph group_response["Incident Response"]
  node_healing["Self-Healing Webhook<br/>[app.py]"]
  node_k8s["Kubernetes API"]
  node_runbook["GitHub Actions Runbook<br/>[self-healing.yml]"]
end

subgraph group_external["External Systems"]
  node_newrelic["New Relic APM"]
  node_pagerduty["PagerDuty"]
  node_discord["Discord"]
end

subgraph group_state["State and Messaging"]
  node_redis[("Redis Cache")]
  node_postgres[("PostgreSQL")]
  node_sqs["AWS SQS"]
  node_dynamodb[("DynamoDB")]
end

node_caller(("API Client"))

node_caller -->|"requests evaluation"| node_evaluation
node_evaluation -->|"gets decision"| node_evaluator
node_evaluator -->|"reads cache"| node_redis
node_evaluator -->|"fetches flag"| node_flag
node_evaluator -->|"fetches rules"| node_targeting
node_flag -->|"validates key"| node_auth
node_targeting -->|"validates key"| node_auth
node_flag -->|"reads and writes flags"| node_postgres
node_targeting -->|"reads and writes rules"| node_postgres
node_auth -->|"validates and stores keys"| node_postgres
node_auth -->|"generates keys"| node_keygen
node_evaluation -->|"publishes event"| node_sqs
node_sqs -->|"delivers messages"| node_analytics
node_analytics -->|"writes events"| node_dynamodb
node_evaluation -->|"exports telemetry"| node_collector
node_flag -->|"exports telemetry"| node_collector
node_targeting -->|"exports telemetry"| node_collector
node_auth -->|"exports telemetry"| node_collector
node_analytics -->|"exports telemetry"| node_collector
node_collector -->|"exports metrics"| node_prometheus
node_collector -->|"pushes logs"| node_loki
node_collector -->|"exports OTLP"| node_newrelic
node_prometheus -->|"feeds dashboards"| node_grafana
node_loki -->|"feeds dashboards"| node_grafana
node_grafana -->|"opens incidents"| node_pagerduty
node_grafana -->|"sends alerts"| node_discord
node_grafana -->|"sends webhook"| node_healing
node_healing -->|"restarts deployment"| node_k8s
node_healing -->|"confirms mitigation"| node_discord
node_healing -->|"dispatches runbook"| node_runbook

click node_evaluation "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/evaluation-service/handlers.go"
click node_evaluator "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/evaluation-service/evaluator.go"
click node_flag "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/flag-service/app.py"
click node_targeting "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/targeting-service/app.py"
click node_auth "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/auth-service/handlers.go"
click node_keygen "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/auth-service/key.go"
click node_analytics "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/analytics-service/app.py"
click node_collector "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/otel-collector.yaml"
click node_prometheus "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/grafana-dashboard.yaml"
click node_loki "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/otel-collector.yaml"
click node_grafana "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/grafana-alerting.yaml"
click node_healing "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/self-healing-service/app.py"
click node_runbook "https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/.github/workflows/self-healing.yml"

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_evaluation,node_evaluator,node_flag,node_targeting,node_auth,node_keygen,node_analytics,node_caller toneBlue
class node_collector,node_prometheus,node_loki,node_grafana toneAmber
class node_healing,node_k8s,node_runbook toneMint
class node_newrelic,node_pagerduty,node_discord toneRose
class node_redis,node_postgres,node_sqs,node_dynamodb toneIndigo
```

## Components

### Flag Platform

- [Evaluation API](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/evaluation-service/handlers.go): `services/evaluation-service/handlers.go`
- [Decision Logic](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/evaluation-service/evaluator.go): `services/evaluation-service/evaluator.go`
- [Flag API](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/flag-service/app.py): `services/flag-service/app.py`
- [Targeting API](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/targeting-service/app.py): `services/targeting-service/app.py`
- [Auth API](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/auth-service/handlers.go): `services/auth-service/handlers.go`
- [API Key Generation](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/auth-service/key.go): `services/auth-service/key.go`
- [Analytics Worker](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/analytics-service/app.py): `services/analytics-service/app.py`

### Observability

- [OTel Collector](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/otel-collector.yaml): `gitops/observability/otel-collector.yaml`
- [Prometheus](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/grafana-dashboard.yaml): `gitops/observability/grafana-dashboard.yaml`
- [Grafana Loki](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/otel-collector.yaml): `gitops/observability/otel-collector.yaml`
- [Grafana Alerts](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/gitops/observability/grafana-alerting.yaml): `gitops/observability/grafana-alerting.yaml`

### Incident Response

- [Self-Healing Webhook](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/services/self-healing-service/app.py): `services/self-healing-service/app.py`
- **Kubernetes API**
- [GitHub Actions Runbook](https://github.com/ricardomarassato/fiap-postech-tc4-togglemaster/blob/main/.github/workflows/self-healing.yml): `.github/workflows/self-healing.yml`

### External Systems

- **New Relic APM**
- **PagerDuty**
- **Discord**

### State and Messaging

- **Redis Cache**
- **PostgreSQL**
- **AWS SQS**
- **DynamoDB**

### Other components

- **API Client**

## Connections

- API Client → Evaluation API: requests evaluation (evidence: `README.md`)
- Evaluation API → Decision Logic: gets decision (evidence: `services/evaluation-service/handlers.go`)
- Decision Logic → Redis Cache: reads cache (evidence: `services/evaluation-service/evaluator.go`)
- Decision Logic → Flag API: fetches flag (evidence: `services/evaluation-service/evaluator.go`)
- Decision Logic → Targeting API: fetches rules (evidence: `services/evaluation-service/evaluator.go`)
- Flag API → Auth API: validates key (evidence: `services/flag-service/app.py`)
- Targeting API → Auth API: validates key (evidence: `services/targeting-service/app.py`)
- Flag API → PostgreSQL: reads and writes flags (evidence: `services/flag-service/app.py`)
- Targeting API → PostgreSQL: reads and writes rules (evidence: `services/targeting-service/app.py`)
- Auth API → PostgreSQL: validates and stores keys (evidence: `services/auth-service/handlers.go`)
- Auth API → API Key Generation: generates keys (evidence: `services/auth-service/handlers.go`)
- Evaluation API → AWS SQS: publishes event (evidence: `README.md`)
- AWS SQS → Analytics Worker: delivers messages (evidence: `README.md`)
- Analytics Worker → DynamoDB: writes events (evidence: `services/analytics-service/app.py`)
- Evaluation API → OTel Collector: exports telemetry (evidence: `README.md`)
- Flag API → OTel Collector: exports telemetry (evidence: `README.md`)
- Targeting API → OTel Collector: exports telemetry (evidence: `README.md`)
- Auth API → OTel Collector: exports telemetry (evidence: `README.md`)
- Analytics Worker → OTel Collector: exports telemetry (evidence: `README.md`)
- OTel Collector → Prometheus: exports metrics (evidence: `README.md`)
- OTel Collector → Grafana Loki: pushes logs (evidence: `README.md`)
- OTel Collector → New Relic APM: exports OTLP (evidence: `README.md`)
- Prometheus → Grafana Alerts: feeds dashboards (evidence: `README.md`)
- Grafana Loki → Grafana Alerts: feeds dashboards (evidence: `README.md`)
- Grafana Alerts → PagerDuty: opens incidents (evidence: `README.md`)
- Grafana Alerts → Discord: sends alerts (evidence: `README.md`)
- Grafana Alerts → Self-Healing Webhook: sends webhook (evidence: `README.md`)
- Self-Healing Webhook → Kubernetes API: restarts deployment (evidence: `services/self-healing-service/app.py`)
- Self-Healing Webhook → Discord: confirms mitigation (evidence: `services/self-healing-service/app.py`)
- Self-Healing Webhook → GitHub Actions Runbook: dispatches runbook (evidence: `README.md`)