1. Frontend Executive Summary
📊 Project Overview
| Project Name | aiusage-app |
| Framework | Angular 15.2.10 |
| TypeScript | 4.9.5 |
| Build Tool | Angular CLI 15.2.11 |
| State Management | RxJS BehaviorSubjects (No NgRx) |
| HTTP Client | Angular HttpClient with 5 Interceptors |
| UI Notifications | ngx-toastr 15.2.2 |
| Charts | Chart.js 4.5.1 |
✅ Production
Auth & Routing
✅ Complete
Role-Based Guards
⚠️ Partial
Admin Portal Pages
✅ Complete
API Integration
Enterprise Readiness: The frontend has a solid architectural foundation with proper
authentication, role-based routing, and API integration. The codebase follows Angular best practices
with lazy loading, dependency injection, and proper separation of concerns.
2. Current Angular Folder Structure
📁 src/app Directory Tree
src/app/
├── app.component.ts # Root component (minimal)
├── app.module.ts # Root module with interceptors
├── app-routing.module.ts # Root routing with lazy loading
│
├── core/ # Singleton services, guards, interceptors
│ ├── config/
│ │ └── app-config.ts # APP_CONFIG injection token
│ ├── guards/
│ │ ├── auth.guard.ts # Authentication check
│ │ ├── admin.guard.ts # Admin/OrgAdmin role check
│ │ ├── super-admin.guard.ts # SuperAdmin role check
│ │ ├── role.guard.ts # Multi-role check
│ │ └── permission.guard.ts # Fine-grained permission check
│ ├── interceptors/
│ │ ├── auth.interceptor.ts # JWT token injection
│ │ ├── org.interceptor.ts # X-Active-Organization-Id header
│ │ ├── loading.interceptor.ts # Loading state management
│ │ ├── retry.interceptor.ts # HTTP retry logic
│ │ └── error.interceptor.ts # Global error handling
│ ├── handlers/
│ │ └── global-error-handler.ts # Uncaught error handling
│ ├── services/
│ │ ├── auth.service.ts # Authentication & JWT
│ │ ├── api.service.ts # Base HTTP wrapper
│ │ ├── org-context.service.ts # Organization context
│ │ ├── permission.service.ts # Permission checks
│ │ ├── loading.service.ts # Loading state
│ │ ├── notification.service.ts # Toast notifications
│ │ ├── subscription-state.service.ts # Subscription validation
│ │ └── export.service.ts # Export functionality
│ ├── models/
│ │ └── subscription-state.model.ts
│ └── core.module.ts # Core module imports
│
├── layout/ # Shell components
│ ├── layout/
│ │ ├── layout.component.ts # Main app shell
│ │ ├── layout.component.html
│ │ └── layout.component.css
│ ├── sidebar/
│ │ ├── sidebar.component.ts # Navigation sidebar
│ │ ├── sidebar.component.html
│ │ ├── sidebar.component.css
│ │ └── nav-menu.config.ts # Navigation menu definition
│ ├── header/
│ │ ├── header.component.ts # Top navigation bar
│ │ ├── header.component.html
│ │ └── header.component.css
│ ├── footer/
│ │ └── footer.component.ts # Footer component
│ └── layout.module.ts # Layout module
│
├── modules/ # Feature modules (lazy loaded)
│ ├── auth/ # Authentication module
│ │ ├── components/
│ │ │ ├── login/
│ │ │ ├── register/
│ │ │ ├── forgot-password/
│ │ │ ├── reset-password/
│ │ │ └── verify-email/
│ │ ├── auth.module.ts
│ │ └── auth-routing.module.ts
│ ├── dashboard/ # Dashboard module
│ │ ├── dashboard.module.ts
│ │ └── dashboard-routing.module.ts
│ ├── users/ # User management
│ │ ├── users.module.ts
│ │ └── users-routing.module.ts
│ ├── organizations/ # Organization management
│ │ ├── organizations.module.ts
│ │ └── organizations.service.ts
│ ├── devices/ # Device management
│ │ └── devices.module.ts
│ ├── agents/ # Agent management
│ │ └── agents.module.ts
│ ├── analytics/ # Analytics & reports
│ │ └── analytics.module.ts
│ ├── billing/ # Billing & plans
│ │ ├── billing.module.ts
│ │ └── plans/
│ │ └── plans.module.ts
│ ├── settings/ # Settings module
│ │ └── settings.module.ts
│ ├── audit-logs/ # Audit log viewing
│ │ └── audit-logs.module.ts
│ ├── hierarchy/ # Organization hierarchy
│ │ └── hierarchy.module.ts
│ ├── data-retention/ # Data retention policies
│ │ └── data-retention.module.ts
│ ├── onboarding/ # Agent onboarding
│ │ └── onboarding.module.ts
│ ├── fleet/ # Fleet management
│ │ └── fleet.module.ts
│ └── profile/ # User profile
│ └── profile.module.ts
│
├── shared/ # Shared components, models, utilities
│ ├── components/
│ │ ├── page-not-found/
│ │ ├── loading-spinner/
│ │ ├── confirm-dialog/
│ │ └── data-table/
│ ├── models/
│ │ ├── user.model.ts # User, AuthUser, JwtClaims
│ │ ├── org-context.model.ts # Organization context
│ │ ├── device.model.ts
│ │ ├── session.model.ts
│ │ └── api-response.model.ts
│ ├── directives/
│ ├── pipes/
│ └── shared.module.ts
│
└── device-setup/ # Public device setup (no auth)
├── device-setup.component.ts
└── device-setup.module.ts
📊 Module Statistics
| Category | Count | Description |
|---|---|---|
| Feature Modules | 16 | Lazy-loaded feature modules |
| Route Guards | 5 | Auth, Admin, SuperAdmin, Role, Permission |
| HTTP Interceptors | 5 | Auth, Org, Loading, Retry, Error |
| Core Services | 10+ | Auth, API, OrgContext, Permissions, etc. |
| Layout Components | 4 | Layout, Sidebar, Header, Footer |
3. Routing Architecture Analysis
🛡️ Route Guard Hierarchy
Route Protection Layers
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 1: AuthGuard (Base Protection) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Applied to: LayoutComponent shell route │
│ Purpose: Blocks unauthenticated access to ALL protected routes │
│ Behavior: │
│ • Authenticated → allow │
│ • Unauthenticated → redirect to /auth/login with returnUrl │
│ │
│ Implementation: │
│ - Uses AuthService.isAuthenticated$ (BehaviorSubject) │
│ - Reacts to real-time session changes │
│ - Preserves attempted URL for post-login redirect │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 2: Role-Specific Guards │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SuperAdminGuard │
│ ─────────────── │
│ Routes: /organizations, /hierarchy, /audit-logs, /data-retention, /plans │
│ Allow: superAdmin only │
│ Redirect: /dashboard (if wrong role) │
│ │
│ AdminGuard │
│ ─────────── │
│ Routes: /users, /agents, /analytics, /billing, /fleet, /onboarding │
│ Allow: admin, orgAdmin (superAdmin passes through) │
│ Redirect: /dashboard (if user/manager) │
│ │
│ RoleGuard (Multi-Role) │
│ ───────────────────── │
│ Routes: /devices (roles: ['orgAdmin', 'admin', 'manager']) │
│ /settings (roles: ['superAdmin', 'orgAdmin', 'admin']) │
│ Allow: Any role in data.roles array │
│ Configuration: Route.data = { roles: ['role1', 'role2'] } │
│ │
│ PermissionGuard (Fine-Grained) │
│ ────────────────────────────── │
│ Purpose: Check specific permissions like 'devices:read' │
│ Status: ⚠️ Infrastructure exists, limited usage │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📍 Complete Route Map
| Route | Module | Guard | Roles | Status |
|---|---|---|---|---|
| /auth/* | AuthModule | None (Public) | All | Production |
| /device/setup | DeviceSetupModule | None (Public) | All | Production |
| /dashboard | DashboardModule | AuthGuard | All Authenticated | Production |
| /super-admin/dashboard | DashboardModule | SuperAdminGuard | superAdmin | Production |
| /organizations | OrganizationsModule | SuperAdminGuard | superAdmin | Production |
| /hierarchy | HierarchyModule | SuperAdminGuard | superAdmin | Partial |
| /audit-logs | AuditLogsModule | SuperAdminGuard | superAdmin | Partial |
| /settings | SettingsModule | RoleGuard | superAdmin, orgAdmin, admin | Production |
| /data-retention | DataRetentionModule | SuperAdminGuard | superAdmin | Planned |
| /billing | BillingModule | AdminGuard | admin, orgAdmin | Partial |
| /plans | PlansModule | SuperAdminGuard | superAdmin | Partial |
| /users | UsersModule | AdminGuard | admin, orgAdmin | Partial |
| /agents | AgentsModule | AdminGuard | admin, orgAdmin | Planned |
| /analytics | AnalyticsModule | AdminGuard | admin, orgAdmin | Partial |
| /devices | DevicesModule | RoleGuard | orgAdmin, admin, manager | Production |
| /onboarding | OnboardingModule | AdminGuard | admin, orgAdmin | Planned |
| /fleet | FleetModule | AdminGuard | admin, orgAdmin | Planned |
| /profile | ProfileModule | AuthGuard | All Authenticated | Production |
🔄 Lazy Loading Configuration
// Example lazy loading pattern from app-routing.module.ts
{
path: 'users',
canActivate: [AdminGuard],
loadChildren: () =>
import('./modules/users/users.module').then((m) => m.UsersModule),
}
Lazy Loading Status: All feature modules use lazy loading. This provides good
code splitting and faster initial page loads. The root module only imports CoreModule, SharedModule,
and LayoutModule.
4. Authentication & Login Flow
🔐 Authentication Architecture Overview
Authentication Flow
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: Login Initiation │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ User enters credentials on /auth/login │
│ │
│ LoginComponent ──► AuthService.login(email, password, rememberMe) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 2: API Authentication │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ POST /api/auth/login │
│ Body: { email, password, deviceId? } │
│ │
│ Response: { │
│ token: "eyJhbGciOiJSUzI1NiIs...", ← JWT access token │
│ refreshToken: "dGhpcyBpcyBhIHJlZnJlc2g...", ← Refresh token │
│ user: { id, email, role, organizationId } │
│ } │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 3: Token Storage & Processing │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ AuthService.processAuthResponse(response): │
│ │
│ 1. Store JWT in: │
│ • rememberMe=true → localStorage (persistent) │
│ • rememberMe=false → sessionStorage (session only) │
│ │
│ 2. Store refreshToken (always localStorage for recovery) │
│ │
│ 3. Decode JWT and extract claims: │
│ • sub (userId) │
│ • email │
│ • organizationId │
│ • role (normalized from PascalCase to camelCase) │
│ • roleLevel (0-4) │
│ • permissions array │
│ │
│ 4. Create AuthUser object and emit to currentUser$ │
│ │
│ 5. Start silent refresh timer (90% of token lifetime) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 4: Organization Context Initialization │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ OrgContextService.initialize(user): │
│ │
│ IF SuperAdmin: │
│ • Load all organizations via OrganizationsService.getOrganizations() │
│ • Emit availableOrgs$ │
│ • Restore active org from sessionStorage (if exists) │
│ • Allow org switching via header dropdown │
│ │
│ IF Standard User (Admin, Manager, User): │
│ • Build context from JWT claims │
│ • Single organization context │
│ • No org switching capability │
│ │
│ Result: OrgContext { id, name, primaryColor, initials } │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 5: Navigation to Default Route │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ AuthService.getDefaultRoute(): │
│ • superAdmin → '/super-admin/dashboard' │
│ • admin → '/dashboard' │
│ • others → '/dashboard' │
│ │
│ Router.navigate([defaultRoute]) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🔄 Token Refresh Flow
Silent Token Refresh
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ Automatic Refresh (Silent) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Timer set to: token.exp - Date.now() * 0.9 │
│ (90% of token lifetime) │
│ │
│ When timer fires: │
│ POST /api/auth/refresh │
│ Body: { refreshToken } │
│ │
│ Success: Update stored tokens, reset timer │
│ Failure: Logout user, redirect to login │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Manual Refresh (On 401 Response) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ API returns 401 Unauthorized │
│ │
│ ErrorInterceptor catches 401: │
│ • Attempt token refresh │
│ • If refresh succeeds: retry original request │
│ • If refresh fails: logout and redirect to login │
│ │
│ ⚠️ Note: ErrorInterceptor not fully implemented (placeholder) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🔑 JWT Claims Structure
// JwtClaims interface (from shared/models/user.model.ts)
interface JwtClaims {
sub: string; // User ID
email: string; // User email
organizationId?: string; // Tenant ID (null for SuperAdmin)
organizationName?: string; // Org name for display
role: UserRole; // 'superAdmin' | 'admin' | 'orgAdmin' | 'manager' | 'user' | 'viewer'
roleLevel?: string; // 0=SuperAdmin, 1=Admin, 2=Manager, 3=User, 4=Viewer
permissions: string[]; // Fine-grained permissions ['devices:read', 'users:write']
iat: number; // Issued at (Unix seconds)
exp: number; // Expiry (Unix seconds)
}
🛡️ AuthService Key Methods
| Method | Purpose | Returns |
|---|---|---|
| login(email, password, rememberMe) | Authenticate user | Observable<LoginResponse> |
| logout() | Clear session | void |
| refreshToken() | Get new access token | Observable<boolean> |
| getCurrentUser() | Get current AuthUser | AuthUser | null |
| decodeToken(token) | Decode JWT claims | JwtClaims |
| normalizeRole(role) | Convert PascalCase to camelCase | UserRole |
| isTokenExpired(token) | Check token expiry | boolean |
| getDefaultRoute() | Get post-login route | string |
📦 Token Storage Strategy
| Storage | Token | Persistence | Use Case |
|---|---|---|---|
| localStorage | JWT + RefreshToken | Across sessions | Remember Me = true |
| sessionStorage | JWT | Single session | Remember Me = false |
| sessionStorage | aiusage_active_org | Single session | SuperAdmin org switcher |
| Memory | AuthUser | Page lifecycle | currentUser$ BehaviorSubject |
5. Current Role Handling
👥 Role Definitions
// UserRole type (from shared/models/user.model.ts)
type UserRole = 'superAdmin' | 'admin' | 'orgAdmin' | 'manager' | 'user' | 'viewer';
// Role levels (from JWT claims)
const ROLE_LEVELS = {
superAdmin: 0, // Cross-tenant access
admin: 1, // Organization Admin
orgAdmin: 1, // Organization Admin (alias)
manager: 2, // Department/Team Manager
user: 3, // Standard user
viewer: 4 // Read-only access
};
📋 Role Implementation Matrix
| Role | Backend | Frontend | JWT Claims | Guard | Status |
|---|---|---|---|---|---|
| SuperAdmin | ✅ Exists | ✅ Full | role: 'superAdmin', roleLevel: 0 | SuperAdminGuard | Production |
| Admin | ✅ Exists | ✅ Full | role: 'admin', roleLevel: 1 | AdminGuard | Production |
| OrgAdmin | ✅ Exists | ✅ Full | role: 'orgAdmin', roleLevel: 1 | AdminGuard | Production |
| Manager | ✅ Exists | ⚠️ Partial | role: 'manager', roleLevel: 2 | RoleGuard | Partial |
| User | ✅ Exists | ⚠️ Partial | role: 'user', roleLevel: 3 | AuthGuard only | Partial |
| Viewer | ⚠️ Exists? | ⚠️ Fallback | role: 'viewer', roleLevel: 4 | Sidebar fallback | Planned |
🎭 Role Hierarchy Visualization
Role Hierarchy & Access Levels
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────┐
│ SuperAdmin │ ← Level 0
│ (Cross-tenant) │
└────────┬────────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Admin │ │ OrgAdmin │ │ (Same │ ← Level 1
│ │ │ │ │ Level) │
└─────┬─────┘ └─────┬─────┘ └───────────┘
│ │
└───────┬───────┘
│
▼
┌────────────┐
│ Manager │ ← Level 2
│(Team/Dept) │
└─────┬──────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ User │ │ Viewer │ │ (Custom) │ ← Levels 3-4
│ │ │(Read-only│ │ │
└──────────┘ └──────────┘ └──────────┘
═══════════════════════════════════════════════════════════════════════════════
Access Inheritance: SuperAdmin > Admin/OrgAdmin > Manager > User > Viewer
═══════════════════════════════════════════════════════════════════════════════
🎯 Sidebar Navigation by Role
// nav-menu.config.ts - Navigation items with role restrictions
export const NAV_MENU: NavItem[] = [
// All authenticated users
{ path: '/dashboard', icon: 'dashboard', label: 'Dashboard', roles: ALL_ROLES },
{ path: '/profile', icon: 'user', label: 'Profile', roles: ALL_ROLES },
// SuperAdmin only
{ path: '/organizations', icon: 'building', label: 'Organizations', roles: ['superAdmin'] },
{ path: '/hierarchy', icon: 'sitemap', label: 'Hierarchy', roles: ['superAdmin'] },
{ path: '/audit-logs', icon: 'file-alt', label: 'Audit Logs', roles: ['superAdmin'] },
{ path: '/data-retention', icon: 'archive', label: 'Data Retention', roles: ['superAdmin'] },
{ path: '/plans', icon: 'credit-card', label: 'Plans', roles: ['superAdmin'] },
// Admin/OrgAdmin
{ path: '/users', icon: 'users', label: 'Users', roles: ['admin', 'orgAdmin'] },
{ path: '/agents', icon: 'robot', label: 'Agents', roles: ['admin', 'orgAdmin'] },
{ path: '/analytics', icon: 'chart-line', label: 'Analytics', roles: ['admin', 'orgAdmin'] },
{ path: '/billing', icon: 'dollar-sign', label: 'Billing', roles: ['admin', 'orgAdmin'] },
{ path: '/onboarding', icon: 'download', label: 'Onboarding', roles: ['admin', 'orgAdmin'] },
{ path: '/fleet', icon: 'server', label: 'Fleet', roles: ['admin', 'orgAdmin'] },
// Admin + Manager
{ path: '/devices', icon: 'laptop', label: 'Devices', roles: ['admin', 'orgAdmin', 'manager'] },
// Multi-role
{ path: '/settings', icon: 'cog', label: 'Settings', roles: ['superAdmin', 'orgAdmin', 'admin'] },
];
⚠️ Role Implementation Gaps:
- Manager Role: Sidebar shows devices, but manager-specific views not implemented
- User Role: Only has access to dashboard and profile, self-service features missing
- Viewer Role: Used as fallback in sidebar, but no explicit viewer pages exist
- Fine-grained Permissions: PermissionService exists but limited usage in templates
6. Layout/UI Architecture
🏗️ Layout Component Structure
Layout Component Hierarchy
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ LayoutComponent (app-layout) │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ HeaderComponent (app-header) ││
│ │ ┌───────────────────────────────────────────────────────────────────┐ ││
│ │ │ • Logo / Brand │ ││
│ │ │ • Organization Switcher (SuperAdmin only) │ ││
│ │ │ • Notification Bell │ ││
│ │ │ • User Profile Dropdown │ ││
│ │ │ • Logout Button │ ││
│ │ └───────────────────────────────────────────────────────────────────┘ ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌──────────────────┐ ┌──────────────────────────────────────────────────┐│
│ │ │ │ ││
│ │ SidebarComponent │ │ Router Outlet (Feature Modules) ││
│ │ (app-sidebar) │ │ ││
│ │ │ │ • Dashboard ││
│ │ ┌──────────────┐ │ │ • Users ││
│ │ │ Nav Items │ │ │ • Devices ││
│ │ │ (Filtered by │ │ │ • Analytics ││
│ │ │ role) │ │ │ • Settings ││
│ │ └──────────────┘ │ │ • etc. ││
│ │ │ │ ││
│ │ ┌──────────────┐ │ │ ││
│ │ │ Collapse │ │ │ ││
│ │ │ Toggle │ │ │ ││
│ │ └──────────────┘ │ │ ││
│ │ │ │ ││
│ └──────────────────┘ └──────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ FooterComponent (app-footer) - Optional ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Mobile Behavior (< 768px):
• Sidebar becomes overlay (full screen)
• Toggle button in header
• Sidebar auto-collapses on navigation
📱 Responsive Design Strategy
| Breakpoint | Behavior | Implementation |
|---|---|---|
| < 768px (Mobile) | Sidebar overlay mode | MOBILE_BREAKPOINT constant in layout.component.ts |
| ≥ 768px (Desktop) | Sidebar inline mode | Collapsible but always visible |
🎨 UI Framework Assessment
| Aspect | Implementation | Status |
|---|---|---|
| CSS Framework | Custom CSS (styles.css ~31KB) | Custom |
| Component Library | None (custom components) | Partial |
| Icons | Font Awesome (assumed from icon names) | Production |
| Notifications | ngx-toastr | Production |
| Charts | Chart.js | Production |
| Theming | Organization-based colors (deterministic HSL) | Production |
| Animations | BrowserAnimationsModule | Production |
⚠️ UI Component Gap: No third-party UI component library (like Angular Material,
NG-ZORRO, or PrimeNG) is used. All components are custom-built. This provides flexibility but
requires more development effort for complex components (data tables, date pickers, etc.).
7. API Integration Structure
🌐 HTTP Interceptor Chain
HTTP Request Flow (Interceptors)
═══════════════════════════════════════════════════════════════════════════════
Request
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. AuthInterceptor │
│ • Adds Authorization header: Bearer ${jwtToken} │
│ • Skips if no token available │
│ • Skips for public endpoints (login, register) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. OrgInterceptor │
│ • Adds X-Active-Organization-Id header │
│ • Critical for SuperAdmin org switching │
│ • Reads from OrgContextService.activeOrgId │
│ • Only applies when activeOrgId is set │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3. LoadingInterceptor │
│ • Sets loading state to true on request start │
│ • Sets loading state to false on response/error │
│ • Triggers loading spinner overlay │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 4. RetryInterceptor │
│ • Retries failed requests up to 3 times │
│ • Exponential backoff between retries │
│ • Only retries on network errors, not 4xx/5xx │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 5. ErrorInterceptor │
│ • Global error handling │
│ • 401 → triggers token refresh │
│ • 403 → shows access denied notification │
│ • Shows toast notification for errors │
│ ⚠️ Currently basic implementation │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
HTTP Client → Backend API
═══════════════════════════════════════════════════════════════════════════════
Response Flow (Reverse Order):
Backend → ErrorInterceptor → RetryInterceptor → LoadingInterceptor
→ OrgInterceptor → AuthInterceptor → Service
📡 Service Architecture
| Service | Purpose | Scope |
|---|---|---|
| ApiService | Base HTTP wrapper with error handling | Core |
| AuthService | Authentication, JWT, tokens | Core |
| OrgContextService | Organization context, SuperAdmin switching | Core |
| PermissionService | Permission checking | Core |
| OrganizationsService | Organization CRUD operations | Feature |
| LoadingService | Loading state management | Core |
| NotificationService | Toast notifications | Core |
| ExportService | Data export functionality | Core |
| SubscriptionStateService | Subscription validation | Core |
| DashboardDateRangeService | Date range state for dashboard | Core |
🔌 API Base URL Configuration
// Environment Configuration
// environments/environment.ts
export const environment = {
production: false,
apiUrl: 'https://localhost:5001/api', // Development
appName: 'AIUsagePlatform'
};
// environments/environment.prod.ts
export const environment = {
production: true,
apiUrl: 'https://api.aiusageplatform.com/api', // Production
appName: 'AIUsagePlatform'
};
// Usage via APP_CONFIG injection token
@Inject(APP_CONFIG) private config: AppConfig
// Service usage
this.http.get(`${this.config.apiUrl}/users`)
📤 HTTP Error Handling Strategy
| Status | Handler | Behavior |
|---|---|---|
| 401 Unauthorized | ErrorInterceptor | Trigger token refresh, retry request |
| 403 Forbidden | ErrorInterceptor | Show "Access Denied" toast |
| 404 Not Found | ApiService | Return null or throw specific error |
| 422 Validation | Component | Display validation errors in form |
| 500+ Server Error | ErrorInterceptor | Show generic error toast |
| Network Error | RetryInterceptor | Retry 3x with backoff, then fail |
8. Current Admin Portal Status
📊 Admin Portal Feature Matrix
| Feature | Route | Backend API | Frontend | Status |
|---|---|---|---|---|
| Dashboard | /dashboard | ✅ /api/admindashboard | ✅ Implemented | Production |
| User Management | /users | ✅ /api/usermanagement | ⚠️ Basic List | Partial |
| Device List | /devices | ✅ /api/admin/organizations/{id}/devices | ✅ Implemented | Production |
| Analytics | /analytics | ✅ /api/analytics | ⚠️ Basic Charts | Partial |
| Billing | /billing | ✅ /api/admin/organizations/{id}/billing | ⚠️ Placeholder | Partial |
| Settings | /settings | ✅ /api/admin/organizations/{id} | ✅ Implemented | Production |
| Agent Management | /agents | ⚠️ Partial | 🔲 Not Started | Planned |
| Onboarding | /onboarding | ✅ /api/onboarding | 🔲 Not Started | Planned |
| Fleet Management | /fleet | ⚠️ Partial | 🔲 Not Started | Planned |
| Export/Reports | Various | ✅ /api/exportjobs | ⚠️ Basic Integration | Partial |
🏗️ Admin Portal Implementation Status
✅ Ready
Dashboard & Devices
⚠️ Partial
Users, Analytics, Billing
🔲 Missing
Agents, Onboarding, Fleet
Admin Portal Architecture: The Admin Portal uses a shared DashboardModule
that renders different views based on the route and user role. The /dashboard route shows
the standard admin dashboard, while /super-admin/dashboard shows the SuperAdmin view.
10. Frontend Technical Debt Review
🐛 Identified Technical Debt
| Category | Issue | Severity | Impact |
|---|---|---|---|
| Components | Limited reusable component library | Medium | Duplicate code across modules |
| UI Framework | No component library (Material, PrimeNG, etc.) | Medium | Custom CSS for every component |
| Role Implementation | Manager and User roles incomplete | High | Limited role-based features |
| Error Handling | ErrorInterceptor is basic | Medium | Inconsistent error UX |
| Admin Pages | Several modules are placeholders | High | Incomplete admin experience |
| Permissions | Fine-grained permissions not fully utilized | Low | Role-only access control |
| Testing | Limited unit test coverage | Medium | Regression risk |
⚠️ Critical Gaps
High Priority Issues
- Incomplete Admin Pages: Agents, Onboarding, Fleet modules exist but are not implemented
- Manager Role: No manager-specific views (team management, approvals)
- User Self-Service: Standard users only have dashboard and profile
- Component Reusability: Data tables, forms duplicated across modules
✅ Strengths
Well-Implemented Areas
- Authentication: Complete JWT flow with refresh tokens
- Routing: Proper lazy loading and role guards
- Tenant Isolation: OrgInterceptor for SuperAdmin context switching
- Architecture: Clean separation of core, shared, and feature modules
- HTTP Layer: Comprehensive interceptor chain
11. Frontend Enterprise Readiness Score
📊 Scoring Matrix
| Category | Score | Status | Notes |
|---|---|---|---|
| Routing Architecture | 9/10 | Excellent | Lazy loading, guards, proper hierarchy |
| Role Governance | 7/10 | Good | Guards complete, but Manager/User roles need work |
| API Integration | 9/10 | Excellent | Interceptors, error handling, org context |
| Authentication | 9/10 | Excellent | JWT, refresh, storage strategy |
| UI Scalability | 5/10 | Needs Work | Missing component library |
| Tenant Awareness | 9/10 | Excellent | OrgInterceptor, context service |
| Code Organization | 8/10 | Good | Clean folder structure, module separation |
| Maintainability | 7/10 | Good | Good patterns, limited test coverage |
| Documentation | 6/10 | Fair | Inline comments good, external docs limited |
| Enterprise Readiness | 7/10 | Good | Solid foundation, needs component library |
🎯 Overall Assessment
76%
Enterprise Ready
7/10
Average Score
✅
Architecture Sound
Verdict: The frontend has a solid architectural foundation suitable
for enterprise development. Authentication, routing, and API integration are production-ready.
The main gaps are in UI component reusability and completion of some feature modules.
Recommended next step: Implement a component library or adopt Angular Material
for faster UI development.
📋 Recommended Priority Order
- Immediate: Complete Admin Portal pages (Agents, Onboarding)
- Short-term: Add component library (Angular Material recommended)
- Medium-term: Implement Manager role views
- Ongoing: Add unit tests for critical services