How hazit90/alarmpoet works
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