# 50fifty/auth-scheduled-backup architecture

> Architecture diagram of the GitHub repository 50fifty/auth-scheduled-backup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/50fifty/auth-scheduled-backup
- Repository: https://github.com/50fifty/auth-scheduled-backup

## Overview

##### Project Type and Purpose
- This is a Firebase Extension written in TypeScript that provides a serverless, event-driven backup service.
- Its sole responsibility is to run a scheduled Cloud Function that fetches all Firebase Authentication users and writes them as a JSON backup file to a Google Cloud Storage bucket.

##### High-Level Architecture Overview
- Components:
- Cloud Scheduler (Cron)
- Cloud Function (the extension code)
- Firebase Authentication service (managed Google service)
- Google Cloud Storage bucket (managed Google service)
- Configuration & IAM (environment variables, service account roles)
- Flow:
1. Cloud Scheduler fires at the configured interval (daily, weekly, etc.).
2. Trigger invokes the Cloud Function entry point (`extension/src/index.ts`).
3. The function reads configuration (bucket name, cron schedule) from environment.
4. It calls the `performBackup` use case, which:
a. Uses `FirebaseAuthService` to list all users via Firebase Admin SDK.
b. Serializes user records into JSON.
c. Uses `GoogleCloudStorageService` to upload the JSON file to the target Cloud Storage bucket.

##### Key Architectural Patterns and Design Principles
- Dependency Injection / Interface Abstraction
- Services live behind `AuthService` and `StorageService` interfaces (in `extension/src/services/interfaces`).
- Enables swapping real implementations (`FirebaseAuthService` / `GoogleCloudStorageService`) with fakes for unit testing.
- Single Responsibility & Clean Layering
- `src/config` handles config parsing.
- `src/usecases` contains business logic (`perform_backup.ts`).
- `src/services` contains integration code with external services.
- Serverless, Event-Driven
- No persistent servers—everything runs on demand in response to the scheduled event.
- Testing Pyramid
- Unit tests use fake service implementations.
- Integration tests hit live Firebase Auth + GCS.
- System tests run end-to-end with emulator or real projects.

A. Cloud Scheduler
B. Cloud Function (Extension)
1. Config Module
2. Use Case Module (`performBackup`)
3. Service Interfaces
4. Service Implementations (FirebaseAuthService, GoogleCloudStorageService)
C. Firebase Authentication API
D. Google Cloud Storage Bucket
- Scheduler → Cloud Function (trigger).
- Cloud Function/Use Case → FirebaseAuthService → Firebase Auth API (read users).
- Cloud Function/Use Case → GoogleCloudStorageService → GCS Bucket (write JSON).
- External Dependencies:
- IAM roles (Service Account with Auth Admin & Storage Admin).

##### Essential Elements
- Clear component names: “Cloud Scheduler”, “Backup Function”, “FirebaseAuthService”, etc.
- Compute vs. Managed Service vs. Config.
- Call out IAM roles needed by the service account.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure
    CloudScheduler["Cloud Scheduler"]:::infra
    CloudSchedulerConfig["Scheduler Config (extension.yaml)"]:::infra
    IAM["IAM (Service Account Roles)"]:::infra

    %% Managed Services
    FirebaseAuthAPI["Firebase Authentication API"]:::managed
    GCSBucket["Google Cloud Storage Bucket"]:::managed

    subgraph "auth-scheduled-backup Extension"
        direction TB
        BackupFunction["Backup Function\n(entry: index.ts)"]:::compute
        EnvVars["Env Vars\n(bucket, schedule)"]:::config
        Manifest["Extension Manifest\n(manifest.ts)"]:::config

        subgraph "Modules"
            direction TB
            ConfigModule["Config Module\n(config.ts)"]:::config
            UseCase["Use Case\n(perform_backup.ts)"]:::compute

            subgraph "Service Interfaces"
                direction TB
                AuthInterface["AuthService Interface"]:::compute
                StorageInterface["StorageService Interface"]:::compute
            end

            subgraph "Service Implementations"
                direction TB
                RealAuth["FirebaseAuthService"]:::compute
                RealStorage["GoogleCloudStorageService"]:::compute
                FakeAuth["FakeAuthService"]:::test
                FakeStorage["FakeStorageService"]:::test
            end
        end
    end

    %% Test Suites
    UnitTests["Unit Tests\ntests/unit-tests"]:::test
    IntegrationTests["Integration Tests\ntests/integration-tests"]:::test
    SystemTests["System Tests\ntests/system-tests"]:::test

    %% Flows
    CloudSchedulerConfig --> CloudScheduler
    CloudScheduler -->|trigger| BackupFunction
    EnvVars --> BackupFunction
    IAM --> BackupFunction

    BackupFunction --> ConfigModule
    BackupFunction --> UseCase

    UseCase -->|uses| AuthInterface
    UseCase -->|uses| StorageInterface

    AuthInterface --> RealAuth
    StorageInterface --> RealStorage

    RealAuth -->|List Users| FirebaseAuthAPI
    RealStorage -->|Upload JSON| GCSBucket

    %% Test mode flows
    UseCase -->|unit test mode| FakeAuth
    UseCase -->|unit test mode| FakeStorage
    FakeAuth -->|simulate| UnitTests
    FakeStorage -->|simulate| UnitTests

    %% Integration/System
    RealAuth --> IntegrationTests
    RealStorage --> IntegrationTests
    FirebaseAuthAPI --> SystemTests
    GCSBucket --> SystemTests

    %% Metadata
    Manifest --> CloudScheduler

    %% Click Events
    click CloudSchedulerConfig "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/extension.yaml"
    click BackupFunction "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/index.ts"
    click ConfigModule "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/config/config.ts"
    click UseCase "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/usecases/perform_backup.ts"
    click AuthInterface "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/interfaces/AuthService.ts"
    click StorageInterface "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/interfaces/StorageService.ts"
    click RealAuth "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/FirebaseAuthService.ts"
    click RealStorage "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/GoogleCloudStorageService.ts"
    click FakeAuth "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/fakes/FakeAuthService.ts"
    click FakeStorage "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/services/fakes/FakeStorageService.ts"
    click Manifest "https://github.com/50fifty/auth-scheduled-backup/blob/main/extension/src/files/manifest.ts"
    click IntegrationTests "https://github.com/50fifty/auth-scheduled-backup/tree/main/extension/tests/integration-tests"
    click SystemTests "https://github.com/50fifty/auth-scheduled-backup/tree/main/extension/tests/system-tests"
    click UnitTests "https://github.com/50fifty/auth-scheduled-backup/tree/main/extension/tests/unit-tests"

    %% Styles
    classDef compute fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef managed fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef infra fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef config fill:#F5F5F5,stroke:#gray,color:#555;
    classDef test fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
```
