# hazit90/alarmpoet architecture

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

- Interactive diagram: https://gitdiagram.com/hazit90/alarmpoet
- Repository: https://github.com/hazit90/alarmpoet

## Overview

##### Project Type and Purpose
- This is a full-stack, hackathon-style alarm application (“AlarmPoet”) that combines:
- A cross-platform Flutter frontend (mobile, web, desktop)
- A Go-based REST API backend for alarm CRUD and poem generation
- A C++-based AI service wrapping LLaMA 3 for poem generation
- A MongoDB (per file tree) or PostgreSQL (per README) database for alarm storage
- Deployment via Kubernetes manifests and Helm charts

##### High-Level File Structure Analysis
- Top-level directories:
- frontend/ — Flutter code (lib/, android/, ios/, web/, windows/, macos/, linux/)
- backend/ — Go service (cmd/, internal/{db,handlers,models,services,utils}, Dockerfile, Makefile)
- ai-service/ — C++ LLaMA wrapper (src/, weights/)
- deploy/ & helm-charts/ — Kubernetes YAMLs and Helm charts for backend, ai-service, and MongoDB/Postgres
- Architectural patterns:
- Frontend ↔ Backend REST calls
- Backend microservices: API server + AI service
- Data persistence via stateful database
- Kubernetes microservice deployment

##### Core Components
a. Frontend
- Flutter app running on user device or web
- api_service.dart communicates with backend over HTTPS
b. Backend API Server
- Exposed endpoints under /v1 (alarms, poems)
- Handlers (alarm.go, poem.go) invoke services
- Services layer implements scheduling and llama_service
- Database adapter (mongodb.go) for CRUD
c. AI Service
- LLaMA-based C++ process (ai-service)
- Accepts REST/gRPC calls from backend to generate poem
- Loads model weights locally
d. Database
- MongoDB (or Postgres) statefulset with PVC
e. Kubernetes Cluster
- Deployments for backend, ai-service, database
- Services for internal communication and external ingress

##### Interactions and Data Flow
- User taps “Set Alarm” in Flutter → Flutter UI calls Backend POST /v1/alarms
- Backend handler writes alarm record to database
- At scheduled time, internal scheduler (or external cronjob) triggers poem generation:
- Backend calls AI service REST/gRPC → returns poem
- Backend updates the alarm record with poem
- Backend may notify frontend via next GET /v1/alarms
- User views poem in Flutter → GET /v1/poems/generate or pulls alarm list

##### Architectural Patterns and Principles
- Layered architecture in backend: Handlers → Services → Models → DB adapter
- Separation of concerns: poem generation isolated in AI microservice
- Stateless API pods; state in database statefulset
- Kubernetes best practices: ServiceAccount, Role/RoleBinding, PVC for DB
- Helm for templated deployments and parameterization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User and Frontend
    User["User"] 
    UI["AlarmPoet Flutter UI"]:::frontend
    APIService["Alarm API Service"]:::frontend
    VM_SetAlarm["Set Alarm ViewModel"]:::frontend
    VM_PoemGen["Poem Gen ViewModel"]:::frontend
    VM_Login["Login ViewModel"]:::frontend

    User -->|"taps Set Alarm"| UI
    UI -->|"POST /v1/alarms"| APIService
    APIService -->|"uses ViewModels"| VM_SetAlarm
    APIService -->|"uses ViewModels"| VM_PoemGen
    APIService -->|"uses ViewModels"| VM_Login

    %% Kubernetes Cluster Boundary
    subgraph "Kubernetes Cluster"
        direction TB

        Ingress["Ingress / API Gateway"]:::ingress

        subgraph "Backend Service" 
            direction TB
            Backend["Go API Server"]:::backend
            Handlers["Handlers"]:::backend
            AlarmHandler["alarm.go"]:::backend
            PoemHandler["poem.go"]:::backend
            Services["Services"]:::backend
            LlamaService["llama_service.go"]:::backend
            DBAdapter["MongoDB Adapter"]:::backend
            MongoDBCode["mongodb.go"]:::backend
            Models["Models"]:::backend
            AlarmModel["alarm.go"]:::backend
            Utils["Utils"]:::backend
            ResponseUtil["response.go"]:::backend
            Dockerfile["Dockerfile"]:::backend
            Makefile["Makefile"]:::backend

            Backend --> Handlers
            Handlers --> AlarmHandler
            Handlers --> PoemHandler
            Backend --> Services
            Services --> LlamaService
            Services --> DBAdapter
            DBAdapter --> MongoDBCode
            Backend --> Models
            Models --> AlarmModel
            Backend --> Utils
            Utils --> ResponseUtil
            Backend --> Dockerfile
            Backend --> Makefile
        end

        subgraph "AI Service"
            direction TB
            AI["LLaMA AI Service"]:::ai
            AISrc["ai-service/src"]:::ai
            AIWeights["ai-service/weights"]:::ai
            AIReadmeSrc["src/README.md"]:::ai
            AIReadmeWeights["weights/README.md"]:::ai
            AI --> AISrc
            AI --> AIWeights
            AISrc --> AIReadmeSrc
            AIWeights --> AIReadmeWeights
        end

        subgraph "Database StatefulSet"
            direction TB
            DB["MongoDB StatefulSet"]:::database
            PVC["PVC"]:::database
            DBService["DB Service"]:::database
            DB --> PVC
            DB --> DBService
        end

        %% Deployment Manifests
        subgraph "Deploy: Direct YAML"
            direction TB
            BE_Deploy["deploy/backend/deployment.yaml"]:::deploy
            BE_Service["deploy/backend/service.yaml"]:::deploy
            BE_Role["deploy/backend/role.yaml"]:::deploy
            BE_RoleBinding["deploy/backend/rolebinding.yaml"]:::deploy
            BE_SA["deploy/backend/serviceaccount.yaml"]:::deploy
            AI_Deploy["deploy/ai-service/deployment.yaml"]:::deploy
            AI_ServiceMan["deploy/ai-service/service.yaml"]:::deploy
            Mongo_Stateset["deploy/mongodb/statefulset.yaml"]:::deploy
            Mongo_PVC["deploy/mongodb/pvc.yaml"]:::deploy
            Mongo_Svc["deploy/mongodb/service.yaml"]:::deploy
        end

        subgraph "Deploy: Helm Charts"
            direction TB
            BE_Chart["helm-charts/backend/Chart.yaml"]:::deploy
            BE_Tmpl["helm-charts/backend/templates/deployment.yaml"]:::deploy
            AI_Chart["helm-charts/ai-service/Chart.yaml"]:::deploy
            AI_Tmpl["helm-charts/ai-service/templates/deployment.yaml"]:::deploy
            PG_Chart["helm-charts/postgres/Chart.yaml"]:::deploy
            PG_Tmpl["helm-charts/postgres/templates/statefulset.yaml"]:::deploy
        end

        %% Service Connections inside Cluster
        Ingress -->|"HTTP /v1/*"| Backend
        Backend -->|"CRUD"| DB
        Backend -->|"gRPC/REST /generate"| AI
    end

    %% External Flow
    APIService -->|"HTTPS"| Ingress

    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef ingress fill:#FFE5B4,stroke:#D2691E,color:#D2691E;
    classDef backend fill:#D6F5D6,stroke:#228B22,color:#228B22;
    classDef ai fill:#E6D6F5,stroke:#800080,color:#800080;
    classDef database fill:#E0E0E0,stroke:#808080,color:#808080;
    classDef deploy fill:#FFF5E6,stroke:#DAA520,color:#DAA520;

    %% Click Events
    click UI "https://github.com/hazit90/alarmpoet/blob/main/frontend/alarm_poet_flutter/lib/main.dart"
    click APIService "https://github.com/hazit90/alarmpoet/blob/main/frontend/alarm_poet_flutter/lib/model/alarm_service.dart"
    click VM_SetAlarm "https://github.com/hazit90/alarmpoet/blob/main/frontend/alarm_poet_flutter/lib/viewmodel/set_alarm_vm.dart"
    click VM_PoemGen "https://github.com/hazit90/alarmpoet/blob/main/frontend/alarm_poet_flutter/lib/viewmodel/poem_gen_vm.dart"
    click VM_Login "https://github.com/hazit90/alarmpoet/blob/main/frontend/alarm_poet_flutter/lib/viewmodel/login_vm.dart"

    click Backend "https://github.com/hazit90/alarmpoet/blob/main/backend/cmd/server/main.go"
    click Dockerfile "https://github.com/hazit90/alarmpoet/tree/main/backend/Dockerfile"
    click Makefile "https://github.com/hazit90/alarmpoet/tree/main/backend/Makefile"
    click AlarmHandler "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/handlers/alarm.go"
    click PoemHandler "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/handlers/poem.go"
    click LlamaService "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/services/llama_service.go"
    click MongoDBCode "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/db/mongodb.go"
    click AlarmModel "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/models/alarm.go"
    click ResponseUtil "https://github.com/hazit90/alarmpoet/blob/main/backend/internal/utils/response.go"

    click AISrc "https://github.com/hazit90/alarmpoet/tree/main/ai-service/src/"
    click AIWeights "https://github.com/hazit90/alarmpoet/tree/main/ai-service/weights/"
    click AIReadmeSrc "https://github.com/hazit90/alarmpoet/blob/main/ai-service/src/README.md"
    click AIReadmeWeights "https://github.com/hazit90/alarmpoet/blob/main/ai-service/weights/README.md"

    click Mongo_Stateset "https://github.com/hazit90/alarmpoet/blob/main/deploy/mongodb/statefulset.yaml"
    click Mongo_PVC "https://github.com/hazit90/alarmpoet/blob/main/deploy/mongodb/pvc.yaml"
    click Mongo_Svc "https://github.com/hazit90/alarmpoet/blob/main/deploy/mongodb/service.yaml"

    click BE_Deploy "https://github.com/hazit90/alarmpoet/blob/main/deploy/backend/deployment.yaml"
    click BE_Service "https://github.com/hazit90/alarmpoet/blob/main/deploy/backend/service.yaml"
    click BE_Role "https://github.com/hazit90/alarmpoet/blob/main/deploy/backend/role.yaml"
    click BE_RoleBinding "https://github.com/hazit90/alarmpoet/blob/main/deploy/backend/rolebinding.yaml"
    click BE_SA "https://github.com/hazit90/alarmpoet/blob/main/deploy/backend/serviceaccount.yaml"
    click AI_Deploy "https://github.com/hazit90/alarmpoet/blob/main/deploy/ai-service/deployment.yaml"
    click AI_ServiceMan "https://github.com/hazit90/alarmpoet/blob/main/deploy/ai-service/service.yaml"

    click BE_Chart "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/backend/Chart.yaml"
    click BE_Tmpl "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/backend/templates/deployment.yaml"
    click AI_Chart "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/ai-service/Chart.yaml"
    click AI_Tmpl "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/ai-service/templates/deployment.yaml"
    click PG_Chart "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/postgres/Chart.yaml"
    click PG_Tmpl "https://github.com/hazit90/alarmpoet/blob/main/helm-charts/postgres/templates/statefulset.yaml"
```
