A3 Architecture

A3 Platform Architecture Reference

Overview

A3 is a full-featured SaaS platform for insurance agent management built by Trusted American Insurance Agency. It provides CRM, enrollment management, commission tracking, compliance tools, and agent support.

Tech Stack

Directory Structure

A3/
├── app/                          # Ember.js frontend application
│   ├── abilities/     (101)      # ember-can permission definitions
│   ├── adapters/      (11)       # Data source adapters
│   ├── builders/      (2)        # API call builders
│   ├── components/    (436)      # Glimmer GTS components
│   ├── config/        (5)        # App configuration
│   ├── controllers/   (varies)   # Controllers (only for query params)
│   ├── handlers/      (2)        # Request handlers
│   ├── helpers/       (2)        # Template helpers
│   ├── models/        (136)      # Ember Data models
│   ├── modifiers/     (1)        # DOM modifiers
│   ├── routes/        (333)      # Route definitions
│   ├── serializers/   (16)       # Data serializers
│   ├── services/      (12)       # Application services
│   ├── session-stores/(1)        # Auth session storage
│   ├── styles/        (1)        # Tailwind CSS entry point
│   ├── templates/     (158)      # GTS route templates
│   ├── transforms/    (5)        # Attribute transforms
│   └── utils/         (19)       # Utility functions
├── functions/                    # Google Cloud Functions backend
│   ├── src/
│   │   ├── auth/                 # Auth triggers
│   │   ├── database/             # Realtime DB triggers
│   │   ├── firestore/            # Firestore document triggers
│   │   ├── https/                # HTTPS endpoints
│   │   ├── pubsub/               # Pub/Sub triggers
│   │   ├── storage/              # Cloud Storage triggers
│   │   ├── models/               # TypeScript interfaces
│   │   ├── types/                # Type definitions
│   │   └── utils/                # Shared utilities
│   └── lib/                      # Compiled output
├── tests/                        # Test suites (807 files)
│   ├── acceptance/               # User flow tests
│   ├── integration/              # Component tests
│   └── unit/                     # Logic tests
├── translations/                 # i18n files
├── types/                        # Global TypeScript types
├── algolia/                      # Algolia search config
├── terraform/                    # Infrastructure as Code
├── emulator-data/                # Firebase emulator snapshots
├── config/                       # Ember.js config
├── docs/                         # Documentation
└── public/                       # Static assets

Data Flow Architecture

Read Flow (Frontend → Firestore)

User visits route
  → Route.model() calls store.query() or store.findRecord()
    → WarpDrive Store dispatches to adapter
      → CloudFirestoreAdapter reads from Firestore
        → CloudFirestoreSerializer normalizes response
          → Store caches record
            → GTS template renders via @model
              → Glimmer component displays data

Write Flow (Frontend → Firestore → Triggers)

User submits form
  → Component @action or ember-concurrency task
    → model.save() via WarpDrive Store
      → CloudFirestoreAdapter writes to Firestore
        → Firestore document created/updated
          → Cloud Function trigger fires
            → Side effects: email, Algolia sync, audit trail, webhooks
              → Real-time listener updates frontend Store
                → Component re-renders with updated data

Third-Party Integration Flow

Frontend component → REST adapter (adapter/firebase.ts)
  → Cloud Function HTTPS endpoint
    → Third-party API (Stripe, Mailgun, PandaDoc, etc.)
      → Response → Firestore document update
        → Real-time listener → Frontend update

Domain Model Map

Core Entities

• Agency — Insurance agency (primary organizational unit)
• User — Platform user (agent, admin, super admin)
• Client — Contact/person being insured
• Carrier — Insurance carrier company

Business Entities

• Enrollment — Insurance enrollment record
• Contract — Agent-carrier contract
• Group — Group insurance plan
• Quote — Insurance quote
• Membership — Client membership

Financial

• Statement — Commission statement
• Transaction — Financial transaction

Communication

• Activity — Audit trail / activity log
• Message — Internal messaging
• Ticket — Support ticket
• Inquiry — Lead inquiry

Associations

• Affiliation — Agent-agency relationship
• License — Agent license record
• Event — Calendar/marketing event

Attachment Patterns

Most entities have associated:

• *-file — File attachments (stored in Cloud Storage)
• *-note — Text notes
• activity — Audit trail entries

Route Map

Public Routes

Authenticated Routes (/a3/...)

Admin Routes (/admin/...)

Service Map

Key Configuration Files

Development Environment

• Frontend dev: ember serve or vite dev
• Backend dev: Firebase Emulator Suite (auth, firestore, functions, storage, pubsub)
• Emulator data: emulator-data/ contains snapshots for seeding
• Tests: ember test (runs in browser via testem)
• Linting: ESLint, Prettier, Stylelint, ember-template-lint

Further Investigation Links

When you need deeper knowledge about specific areas:

• Ember.js: https://guides.emberjs.com/release/
• Glimmer Components: https://guides.emberjs.com/release/components/
• WarpDrive/Ember Data: https://api.emberjs.com/ember-data/release
• Firestore: https://firebase.google.com/docs/firestore
• Cloud Functions: https://firebase.google.com/docs/functions
• Tailwind CSS: https://tailwindcss.com/docs
• ember-cloud-firestore-adapter: https://github.com/nickersk/ember-cloud-firestore-adapter
• ember-simple-auth: https://ember-simple-auth.com/
• ember-can: https://github.com/minutebase/ember-can
• ember-concurrency: https://ember-concurrency.com/
• XState: https://stately.ai/docs