| name | a3-architecture |
| description | Complete architecture reference for the A3 insurance platform — file locations, data flow, conventions, microservice map, and fullstack patterns |
| version | 0.1.0 |
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
| Layer | Technology |
|---|
| Frontend | Ember.js 6.9 (Octane) with TypeScript, Glimmer GTS components |
| Build | Vite + Embroider |
| Styling | Tailwind CSS 4 + Bootstrap 5 |
| State | WarpDrive (next-gen Ember Data) |
| Database | Cloud Firestore (NoSQL) |
| Realtime DB | Firebase Realtime Database (status tracking) |
| File Storage | Google Cloud Storage |
| Auth | Firebase Authentication + ember-simple-auth |
| Backend | Google Cloud Functions (Node.js 22, TypeScript) |
| Search | Algolia |
| Payments | Stripe |
| Email | Mailgun |
| Documents | PandaDoc |
| CRM Sync | HubSpot, Salesforce |
| Error Tracking | Sentry |
| Customer Support | Intercom |
| State Machines | XState 5 |
| Charts | Highcharts 12 |
| Maps | Google Maps |
| Deployment | Netlify (frontend), GCP (backend) |
| IaC | Terraform |
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 notesactivity — Audit trail entries
Route Map
Public Routes
| Route | Purpose |
|---|
/login | User authentication |
/register | New user registration |
/reset | Password reset |
/onboarding | Post-registration setup |
/client/:id | Public client profile |
/client-form/:id | Public client form |
/order/:id | Order page |
/session | Session management |
Authenticated Routes (/a3/...)
| Route | Purpose |
|---|
/a3 | Dashboard |
/a3/clients | Client (contact) management |
/a3/enrollments | Enrollment management |
/a3/groups | Group management |
/a3/agencies | Agency management |
/a3/carriers | Carrier information |
/a3/contracting | Contract management |
/a3/statements | Commission statements |
/a3/settings | User settings |
/a3/tools | Quote tools |
/a3/calendar | Calendar |
/a3/leads | Lead management |
/a3/notifications | Notifications |
/a3/search | Global search |
/a3/support | Support tickets |
/a3/resources | Resources |
/a3/knowledge-hub | Knowledge base |
/a3/marketing-events | Marketing events |
/a3/readiness-report | Readiness report |
/a3/services | Services (websites) |
Admin Routes (/admin/...)
| Route | Purpose |
|---|
/admin/accounting | Financial management |
/admin/agencies | Agency administration |
/admin/carriers | Carrier management |
/admin/clients | Client administration |
/admin/contracting | Contract admin |
/admin/enrollments | Enrollment admin |
/admin/enrollment-issues | Issue tracking |
/admin/events | Event management |
/admin/groups | Group admin |
/admin/inquiries | Lead/inquiry management |
/admin/marketing | Marketing tools |
/admin/messages | Messaging |
/admin/notifications | Notification management |
/admin/products | Product management |
/admin/reporting | Reports |
/admin/search | Admin search |
/admin/settings | System settings |
/admin/tickets | Support ticket admin |
/admin/users | User management |
Service Map
| Service | File | Purpose |
|---|
store | app/services/store.ts | WarpDrive data store with custom aggregation methods |
session | app/services/session.ts | Firebase Auth + MFA + ember-simple-auth |
current-user | app/services/current-user.ts | Loaded user data and permissions |
search | app/services/search.ts | Algolia search integration |
pdf | app/services/pdf.ts | PDF generation/manipulation |
csv | app/services/csv.ts | CSV export |
xlsx | app/services/xlsx.ts | Excel export |
analytics | app/services/analytics.ts | Event tracking |
tour | app/services/tour.ts | Shepherd.js onboarding tour |
recent-records | app/services/recent-records.ts | Recently viewed record tracking |
Key Configuration Files
| File | Purpose |
|---|
app/config/environment.js | Firebase config, API endpoints, feature flags |
firebase.json | Firebase project config, emulator settings |
firestore.rules | Firestore security rules (~101KB) |
firestore.indexes.json | Composite indexes (~235KB) |
storage.rules | Cloud Storage security rules |
database.rules.json | Realtime Database rules |
ember-cli-build.js | Build config (Embroider, split routes) |
vite.config.mjs | Vite build config (Tailwind, PWA) |
app/router.ts | Route definitions |
tsconfig.json | TypeScript configuration |
netlify.toml | Netlify deployment config |
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:
