# bazieebenezer/anam-app architecture

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

- Interactive diagram: https://gitdiagram.com/bazieebenezer/anam-app
- Repository: https://github.com/bazieebenezer/anam-app

## Overview

##### Project type and purpose
- ANAM is a full-stack, multi-channel information platform built with a single Ionic/Angular codebase for Web, iOS and Android.
- It delivers weather bulletins and event notifications to general users and institution-level users, with role-based access and PDF export.
- The backend is serverless (Firebase) plus a small Node.js micro-service for push notifications, and an email-server for outbound email.

##### File-structure overview and architectural clues
- Top level
- capacitor.config.ts, firebase.json, ionic.config.json → configuration for Capacitor and Firebase hosting/integration
- android/ and ios/ → native project wrappers generated by Capacitor
- anam-server/ → Node.js micro-service that listens to Firestore and triggers FCM pushes
- email-server/ → standalone service for sending emails (package.json present)
- src/ → Ionic/Angular application code (components, pages, services, guards, model)
- docs/ → feature and architecture documentation
- Key patterns
- src/app/services → thin Angular services interacting with Firebase SDK and Capacitor plugins
- src/environments → environment-specific Firebase config
- angular.json, tsconfig.json → standard Angular workspace

##### Main system components
A. Client layer (Ionic/Angular)
- Shared codebase: src/app/components, pages, services, guards
- PDF generation service (html2canvas → jsPDF → @capacitor/filesystem → file-opener)
- Authentication flow: AuthService, onboarding, role guards
- Push subscription: FcmService with Capacitor Push and Community FCM plugin
B. Capacitor bridge
- Provides access to native APIs (camera, filesystem, preferences, social-login, push notifications)
- Generates Android (android/) and iOS (ios/) projects
C. Firebase (managed cloud services)
- Authentication (Firebase Auth)
- Firestore (NoSQL real-time DB) for users, bulletins, events
- Cloud Storage (object store for images after refactor)
- Cloud Messaging (FCM)
- (Optionally Cloud Functions for secure role elevation and image processing)
D. Node.js micro-service (anam-server)
- Listens to Firestore onSnapshot events
- Builds FCM topics and sends push notifications via Firebase Admin SDK
E. Email-server
- Sends email notifications or reports (could be triggered by Cloud Functions or by Node micro-service)

##### Relationships and data flows
- The Ionic app communicates directly with Firebase services via SDK over HTTPS / WebSockets:
- AuthService ↔ Firebase Auth
- EventService/PublicationService ↔ Firestore reads/writes
- ImageUploadService ↔ Cloud Storage (upload) → returns URL → stored in Firestore
- FcmService ↔ FCM (subscribe/unsubscribe to topics)
- The Node micro-service uses Firebase Admin SDK:
- Connects to Firestore → listens for new bulletins/events
- Constructs FCM topic names (newPosts, institution_{id}) → sends push notifications
- PDF export: Angular app renders invisible DOM → html2canvas captures → jsPDF outputs → file handled by Capacitor
- Email-server: invoked either by HTTP request or Cloud Function trigger to send email via SMTP/API

##### Architectural patterns and principles
- Separation of concerns: UI (components/pages), business logic (services), persistence (Firebase)
- Event-driven micro-service for notifications (decoupled push logic)
- Pub/Sub with FCM topics for broad vs. targeted notifications
- Feature modules (auth, onboarding, publications, PDF, theme) in Angular
- Role-based access control using guards and Custom Claims (recommended)
- Single codebase supporting multi-platform via Capacitor

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Components["UI Components"]:::client
        Pages["Pages"]:::client
        Tabs["Tabs Navigation"]:::client
        subgraph "Guards"
            direction TB
            AuthGuard["Auth Guard"]:::client
            OnboardingGuard["Onboarding Guard"]:::client
        end
        subgraph "Services"
            direction TB
            AuthService["Auth Service"]:::client
            OnboardingService["Onboarding Service"]:::client
            EventService["Event Service"]:::client
            PublicationService["Publication Service"]:::client
            PdfService["PDF Generation Service"]:::client
            FcmService["FCM Service"]:::client
            StorageService["Storage Service"]:::client
            ImageDownloadService["Image Download Service"]:::client
            ConnectivityService["Connectivity Service"]:::client
            ThemeService["Theme Service"]:::client
            ShareService["Share Service"]:::client
        end
        SignInPage["Sign-In Page"]:::client
        SignUpPage["Sign-Up Page"]:::client
        PdfFlow["PDF Export Flow"]:::client
    end

    %% Capacitor Bridge Layer
    subgraph "Capacitor Bridge" 
        direction TB
        CapacitorConfig["capacitor.config.ts"]:::bridge
        AndroidWrapper["Android Wrapper"]:::bridge
        iOSWrapper["iOS Wrapper"]:::bridge
    end

    %% Firebase Managed Services
    subgraph "Firebase Services" 
        direction TB
        Auth["Firebase Auth"]:::cloud
        Firestore["Firestore (NoSQL DB)"]:::db
        Storage["Cloud Storage"]:::db
        FCM["FCM (Cloud Messaging)"]:::cloud
        Functions["Cloud Functions"]:::cloud
    end

    %% Custom Services
    subgraph "Custom Services" 
        direction TB
        NodeService["Push Micro-Service"]:::custom
        EmailService["Email Notification Service"]:::custom
    end

    %% Documentation
    Docs["Documentation (docs/)"]:::docs

    %% Connections: Client to Firebase
    AuthService -->|"REST/WebSocket"| Auth
    EventService -->|"read/write"| Firestore
    PublicationService -->|"read/write"| Firestore
    StorageService -->|"upload/download"| Storage
    StorageService -->|"URL stored"| Firestore
    FcmService -->|"subscribe/unsubscribe"| FCM
    PdfFlow -->|"html2canvas→jsPDF→Filesystem"| CapacitorConfig
    SignInPage -->|"login/signup"| AuthService
    SignUpPage -->|"register"| AuthService

    %% Capacitor Bridge connections
    Components -->|uses| CapacitorConfig
    Pages -->|builds to| AndroidWrapper
    Pages -->|builds to| iOSWrapper
    StorageService -->|Capacitor FS| CapacitorConfig

    %% Node micro-service listening to Firestore and sending FCM
    Firestore -->|"onSnapshot"| NodeService
    NodeService -->|"Admin SDK"| FCM

    %% Email service trigger
    Functions -->|"HTTP Trigger"| EmailService

    %% Docs linking
    Docs -.-> Components
    Docs -.-> NodeService

    %% Click events
    click Components "https://github.com/bazieebenezer/anam-app/tree/master/src/app/components"
    click Pages "https://github.com/bazieebenezer/anam-app/tree/master/src/app/pages"
    click Tabs "https://github.com/bazieebenezer/anam-app/blob/master/src/app/tabs/tabs.page.ts"
    click AuthGuard "https://github.com/bazieebenezer/anam-app/blob/master/src/app/guards/auth.guard.ts"
    click OnboardingGuard "https://github.com/bazieebenezer/anam-app/blob/master/src/app/guards/onboarding.guard.ts"
    click AuthService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/auth/auth.service.ts"
    click OnboardingService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/onboarding.service.ts"
    click EventService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/evenments/event.service.ts"
    click PublicationService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/publication/publication.service.ts"
    click PdfService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/pdf-generation.service.ts"
    click FcmService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/fcm/fcm.service.ts"
    click StorageService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/storage/storage.service.ts"
    click ImageDownloadService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/image-download.service.ts"
    click ConnectivityService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/connectivity/connectivity.service.ts"
    click ThemeService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/theme.service.ts"
    click ShareService "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/share.service.ts"
    click PdfFlow "https://github.com/bazieebenezer/anam-app/blob/master/src/app/services/pdf-generation.service.ts"
    click SignInPage "https://github.com/bazieebenezer/anam-app/blob/master/src/app/pages/auth/signin/signin.page.ts"
    click SignUpPage "https://github.com/bazieebenezer/anam-app/blob/master/src/app/pages/auth/signup/signup.page.ts"
    click CapacitorConfig "https://github.com/bazieebenezer/anam-app/blob/master/capacitor.config.ts"
    click AndroidWrapper "https://github.com/bazieebenezer/anam-app/tree/master/android/"
    click iOSWrapper "https://github.com/bazieebenezer/anam-app/tree/master/ios/"
    click EnvDev "https://github.com/bazieebenezer/anam-app/blob/master/src/environments/environment.ts"
    click EnvProd "https://github.com/bazieebenezer/anam-app/blob/master/src/environments/environment.prod.ts"
    click FirebaseConfig "https://github.com/bazieebenezer/anam-app/blob/master/firebase.json"
    click NodeService "https://github.com/bazieebenezer/anam-app/blob/master/anam-server/index.js"
    click EmailService "https://github.com/bazieebenezer/anam-app/blob/master/email-server/package.json"
    click Docs "https://github.com/bazieebenezer/anam-app/tree/master/docs/"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#2A75BB,color:#0B3D91
    classDef bridge fill:#E8F0FE,stroke:#4285F4,color:#174EA6
    classDef cloud fill:#E6F4EA,stroke:#34A853,color:#0C6348
    classDef db fill:#FFF4E5,stroke:#FBBC05,color:#A36E00
    classDef custom fill:#FFEDE1,stroke:#EA4335,color:#A42E1E
    classDef docs fill:#F0F0F0,stroke:#888888,color:#333333
```
