Mnemonica Backlot - Architecture Documentation ¶

Version: 3.0.0
Last Updated: 2026-02-03
Status: Production-ready with ongoing improvements

Overview ¶

Mnemonica Backlot is a modern Angular standalone application for managing contracts, projects, templates, and consumption tracking. It follows Angular best practices with a clean separation of concerns and modular architecture.

Technology Stack ¶

Frontend ¶

• Framework: Angular 21.x (Standalone Components)
• UI Library: Angular Material 21.x (Material Design 3)
• State Management: Angular Signals
• Reactive Programming: RxJS 7.8.x
• Language: TypeScript 5.7.x (Strict Mode)
• Styling: SCSS with Material Design theming

Backend Integration ¶

• API: n8n Workflow Automation
• Database: PostgreSQL (via n8n)
• Protocol: REST over HTTP

Development Tools ¶

• Node.js: 22.x (LTS: Jod) via nvm
• Package Manager: npm 10.x
• Build Tool: Angular CLI with Vite
• Linting: ESLint
• Version Control: Git

Application Architecture ¶

High-Level Structure ¶

┌──────────────────────────────────────────┐
│          User Interface (Browser)         │
│                                           │
│  ┌─────────────────────────────────────┐ │
│  │  Angular Application (Port 4200)     │ │
│  │                                       │ │
│  │  ┌────────────┐    ┌──────────────┐ │ │
│  │  │   Core/    │◄──►│   Features/  │ │ │
│  │  │  Services  │    │  Components  │ │ │
│  │  └────────────┘    └──────────────┘ │ │
│  │         │                  │         │ │
│  │  ┌────────────┐    ┌──────────────┐ │ │
│  │  │   Models   │    │    Shared/   │ │ │
│  │  │Interfaces  │    │  Components  │ │ │
│  │  └────────────┘    └──────────────┘ │ │
│  └─────────────────────────────────────┘ │
└──────────────────────────────────────────┘
                    │ HTTP
                    ▼
┌──────────────────────────────────────────┐
│      n8n Workflow Automation API         │
│                                           │
│  ┌─────────────────────────────────────┐ │
│  │  Webhook Endpoints                   │ │
│  │  - contracts-crud                    │ │
│  │  - contract-templates                │ │
│  │  - consumption                       │ │
│  │  - projects                          │ │
│  └─────────────────────────────────────┘ │
└──────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────┐
│           PostgreSQL Database             │
└──────────────────────────────────────────┘

Directory Structure ¶

src/
├── app/
│   ├── core/                    # Core module (singleton services, models)
│   │   ├── models/              # TypeScript interfaces and types
│   │   │   ├── api.model.ts     # API response types
│   │   │   ├── contract.model.ts
│   │   │   ├── project.model.ts
│   │   │   ├── template.model.ts
│   │   │   ├── owner.model.ts
│   │   │   └── index.ts         # Barrel export
│   │   └── services/            # Application-wide services
│   │       ├── api.service.ts   # HTTP client wrapper
│   │       ├── logger.service.ts
│   │       ├── utils.service.ts
│   │       ├── theme.service.ts
│   │       └── preferences.service.ts
│   │
│   ├── features/                # Feature modules (lazy loaded)
│   │   ├── contracts/           # Contract management
│   │   │   ├── components/
│   │   │   │   ├── contracts-list/
│   │   │   │   └── contract-modal/
│   │   │   ├── services/
│   │   │   │   ├── contracts.service.ts
│   │   │   │   └── contract-modal.service.ts
│   │   │   └── contracts.component.ts
│   │   ├── projects/            # Project management
│   │   ├── templates/           # Template management
│   │   ├── consumption/         # Consumption tracking
│   │   └── diagnostics/         # System diagnostics
│   │
│   ├── shared/                  # Shared module
│   │   ├── components/          # Reusable components
│   │   │   ├── navigation/
│   │   │   ├── filter-panel/
│   │   │   └── logo-horiz-animated/
│   │   └── styles/              # Shared styles
│   │
│   ├── app.component.ts         # Root component
│   ├── app.config.ts            # Application configuration
│   └── app.routes.ts            # Route configuration
│
├── environments/                # Environment configs
│   ├── environment.ts
│   └── environment.prod.ts
│
├── styles/                      # Global styles
│   └── styles.scss
│
└── assets/                      # Static assets

n8n/                             # n8n workflow definitions
├── contracts-management.json    # Unified workflow (29 endpoints, 360+ nodes)
└── scripts/                     # Workflow sync scripts

Core Architectural Patterns ¶

1. Standalone Components ¶

All components use Angular's standalone architecture (no NgModules):

@Component({
  selector: 'app-contracts',
  standalone: true,
  imports: [CommonModule, MatTableModule, /* ... */],
  template: `...`
})
export class ContractsComponent {}

Benefits:

• Simplified dependency management
• Better tree-shaking
• Faster compilation
• Easier testing

2. Smart/Dumb Component Pattern ¶

Smart Components (Container/Feature)

• Handle business logic
• Interact with services
• Manage state
• Example: contracts.component.ts, projects.component.ts

Dumb Components (Presentational)

• Pure UI rendering
• Receive data via @Input()
• Emit events via @Output()
• Example: filter-panel.component.ts

3. Signal-Based State Management ¶

Uses Angular Signals for reactive state:

// Reactive state
projects = signal<Project[]>([]);
loading = signal(false);
error = signal<string | null>(null);

// Computed values
filteredProjects = computed(() => {
  return this.projects().filter(/* ... */);
});

// Effects
effect(() => {
  console.log('Projects changed:', this.projects());
});

Benefits:

• Fine-grained reactivity
• Better performance
• Simpler than RxJS for local state
• Type-safe

4. Lazy Loading ¶

All feature routes are lazy-loaded:

{
  path: 'contracts',
  loadComponent: () => import('./features/contracts/contracts.component')
    .then(m => m.ContractsComponent)
}

Benefits:

• Faster initial load
• Code splitting
• On-demand loading

5. Service Layer Pattern ¶

Services handle all business logic and API communication:

@Injectable({ providedIn: 'root' })
export class ApiService {
  getContracts(): Observable<ApiResponse<Contract[]>> {
    return this.http.get<Contract[]>(url).pipe(
      catchError(this.handleError),
      map(this.transformResponse)
    );
  }
}

Data Flow ¶

Request Flow ¶

Component
   │
   │ 1. User Action
   ├──────────► Service
   │              │
   │              │ 2. HTTP Request
   │              ├──────────► n8n API
   │              │              │
   │              │              │ 3. Database Query
   │              │              ├──────────► PostgreSQL
   │              │              │
   │              │              │ 4. Response
   │              │              ◄──────────┤
   │              │ 5. Transform
   │              ◄──────────┤
   │ 6. Update Signal
   ◄──────────┤
   │
   │ 7. UI Update (automatic)
   └──────────► View

State Management Flow ¶

User Action → Component Method → Service Call → Signal Update → View Render

API Integration Architecture ¶

n8n Webhook Structure ¶

All endpoints are served via a single unified n8n webhook workflow. See N8N_WORKFLOW_REFERENCE.md for complete API reference.

Unified Workflow: contracts-management.json (29 endpoints)

• Contracts CRUD, Periods, Prepaid purchases
• Projects listing and assignment
• Plans and Price Lists CRUD
• Usage monitoring and Alerts
• Consumption data
• Pricing calculation

Note: Some endpoints require webhook path prefixes (e.g., /get-plan-by-id/api/v1/plans/:id).
See OpenAPI Specification for authoritative paths.

API Service Pattern ¶

// 1. Define request
getContracts(params?: QueryParams): Observable<ApiResponse<Contract[]>> {

// 2. Build URL with params
const url = `${this.baseUrl}/contracts${queryString}`;

// 3. Make HTTP call
return this.http.get<any>(url).pipe(

  // 4. Handle errors
  catchError(this.handleError),

  // 5. Transform N8N response
  switchMap(response => this.transformResponse(response))
);
}

Component Lifecycle ¶

Standard Component Lifecycle ¶

export class MyComponent implements OnInit, OnDestroy {
  private subscriptions: Subscription[] = [];

  constructor(private service: MyService) {
    // Dependency injection
  }

  ngOnInit(): void {
    // Initialize component
    // Load data
    // Setup subscriptions
    const sub = this.service.getData().subscribe(/*...*/);
    this.subscriptions.push(sub);
  }

  ngOnDestroy(): void {
    // Clean up subscriptions
    this.subscriptions.forEach(sub => sub.unsubscribe());
  }
}

Routing Architecture ¶

Route Configuration ¶

export const routes: Routes = [
  {
    path: '',
    redirectTo: '/contracts',
    pathMatch: 'full'
  },
  {
    path: 'contracts',
    loadComponent: () => import('./features/contracts/contracts.component')
      .then(m => m.ContractsComponent)
  },
  // ... other routes
  {
    path: '**',
    redirectTo: '/contracts'
  }
];

Navigation Flow ¶

User clicks navigation → Router activates route → Lazy load component → Render view

Security Considerations ¶

Current Implementation ¶

• Client-side only (no authentication yet)
• HTTPS enforced in production
• CORS configured on n8n side
• Input validation on forms
• SQL injection prevented by n8n parameterized queries

Future Enhancements ¶

• JWT authentication
• Role-based access control
• Route guards
• API key management

Performance Optimization ¶

Implemented Optimizations ¶

1. Lazy Loading: All feature modules loaded on-demand
2. Virtual Scrolling: For large data sets (TODO)
3. OnPush Change Detection: Where applicable
4. Signal-based updates: Fine-grained reactivity
5. HTTP Caching: Via interceptors (TODO)
6. Bundle Optimization: Code splitting, tree-shaking

Build Output ¶

• Initial Bundle: ~899 KB
• Lazy Chunks: 11 chunks (28-162 KB each)
• Compression: Gzip enabled in production

Testing Strategy (Future) ¶

Unit Tests ¶

• Services: Business logic testing
• Components: Isolated component testing
• Models: Data transformation testing

Integration Tests ¶

• API service mocking
• Component + Service integration

E2E Tests ¶

• Critical user flows
• Cypress or Playwright

Deployment Architecture ¶

Development ¶

npm start → ng serve → localhost:4200

Production Build ¶

npm run build → dist/ → Static hosting

Hosting Options ¶

• Nginx static hosting
• Cloud providers (AWS S3, Google Cloud Storage, Azure Blob)
• CDN distribution

Future Architecture Enhancements ¶

1. State Management: Consider NgRx for complex state
2. PWA: Offline support with Service Workers
3. Internationalization: Multi-language support
4. Testing: Comprehensive test suite
5. CI/CD: Automated testing and deployment
6. Monitoring: Error tracking and analytics
7. Authentication: User management system

Path Aliases ¶

Configured in tsconfig.json:

"paths": {
  "@core/*": ["src/app/core/*"],
  "@shared/*": ["src/app/shared/*"],
  "@features/*": ["src/app/features/*"],
  "@environments/*": ["src/environments/*"]
}

Usage:

// Instead of: import { ApiService } from '../../core/services/api.service';
import { ApiService } from '@core/services/api.service';

References ¶

• CLAUDE.md - Development guidelines
• NODE_VERSION_SETUP.md - Environment setup
• Angular Documentation
• Angular Material
• n8n Documentation

Maintained By: Development Team
Last Review: 2026-01-08