# QMF Architecture Guide

## Overview

QMF (Quizzman Modular Framework) is a scalable, layered frontend framework architecture designed for building modular web applications. This document outlines the high-level architectural principles used internally. Implementation details and specific package names are subject to change.

## Architectural Principles

### Layered Design
The framework follows a strict layering principle to manage dependencies and maintain separation of concerns:

- **Foundation Layer**: Core utilities and design tokens with no external dependencies
- **Runtime Layer**: Core infrastructure for state management, event handling, and lifecycle management
- **Component Layer**: Reusable UI primitives and components
- **Module Layer**: Business-level features that compose into complete applications

### Dependency Management
- Strict uni-directional dependency flow from higher layers to lower layers
- Lower layers have no knowledge of upper layers
- Cross-module communication via well-defined interfaces only

### Module Isolation
Each logical feature operates as an isolated module with:
- Independent state management
- Standardized lifecycle
- Error isolation (one module's failure doesn't impact others)
- Configurable initialization

## Core Architecture Components

### State Management
The framework provides:
- **Global state container**: Shared application state (authentication, theme, localization)
- **Module-scoped state**: Isolated per-feature state to prevent cross-contamination
- **Schema validation**: Type-safe state updates with runtime validation
- **Observers**: Reactive state watchers for UI updates

### Event Bus System
Cross-module communication through a pub/sub event system:
- **Scoped events**: Module-to-module communication
- **Global events**: Application-wide notifications
- **Event naming conventions**: Standardized event namespacing
- **Event tracing**: Optional debugging capability for event flows

### Dependency Injection
Modular service registration and resolution:
- **Service registration**: Plugins can register services for other modules
- **Lazy resolution**: Services are resolved on-demand
- **Singleton pattern**: Services maintain single instances across the application
- **Pre-registered services**: Standard framework services available to all modules

### Error Handling & Recovery
Robust error handling architecture:
- **Module-level error boundaries**: Failures isolated to individual features
- **Error events**: Errors propagated through event system for centralized handling
- **Recovery strategies**: Optional retry and fallback mechanisms
- **Logging & monitoring**: All errors captured for debugging

## Module Lifecycle

Each feature module follows a standardized lifecycle:

```
Created → Initialized → Mounted → Connected → Ready 
→ Disconnecting → Destroyed
```

Key stages:
- **Initialization**: Configuration validation and setup
- **Mounting**: DOM attachment and event listener registration
- **Connection**: External service and API initialization
- **Ready**: Module fully operational
- **Cleanup**: Resource deallocation and listener removal

## Plugin Architecture

Modules can be dynamically loaded and composed:
- **Eager loading**: Pre-bundled modules loaded at initialization
- **Lazy loading**: Code-split modules loaded on-demand
- **Dependency resolution**: Automatic topological sort for plugin ordering
- **Configuration injection**: Each module declares required configuration schema

## Build & Distribution Strategy

The framework uses a monorepo structure with:
- **Independent packaging**: Each component is separately buildable
- **Tree-shaking**: Optimized bundle sizes through ES modules
- **Pre-computed artifacts**: Build outputs include hashes and manifests
- **Multi-format output**: Support for different module consumption patterns

### Production Deployment
- Minified and optimized assets
- Subresource integrity hashing
- Content delivery optimization
- Cache-busting through versioning

### Static Asset Pipeline
- Logo assets are generated from canonical source files instead of being edited variant-by-variant.
- The source of truth for logo paths is `assets/logo/logo-config.json`.
- Standard variants and favicon PNGs are regenerated before build and deploy steps.
- Teams should update the canonical logo source, then regenerate assets, rather than editing size-specific files manually.

### Logo Convention
- `<subsystem>-logo.png` is the canonical source for standard logo variants.
- `<subsystem>-logo-512-square.png` is the canonical source when a square variant family is required.
- Generated outputs include the size-suffixed variants and favicon PNG derivatives.
- Temporary working files such as trimmed/original exports should stay outside the published repository.

## Performance Considerations

### Bundle Optimization
- Code splitting by feature module
- Lazy loading for non-critical features
- Shared dependency deduplication
- Tree-shaking to remove unused code

### Runtime Performance
- Efficient pub/sub event system
- Memoized selectors for state queries
- Optimized DOM manipulation
- Event delegation patterns

## Security Architecture

### Data Isolation
- Module state is not accessible across module boundaries
- Event bus communication is the only inter-module data channel
- Type validation at state boundaries

### Runtime Safety
- Configuration schema validation on initialization
- Type checking through runtime validation
- Error isolation prevents cascading failures

## Developer Experience

### Configuration
Modules use declarative schemas with validation:
- Type-safe configuration objects
- Runtime validation with descriptive error messages
- Sensible defaults for optional parameters
- Environment-aware configuration

### Debugging
Built-in debugging capabilities:
- Event trace inspection
- State snapshots
- Module lifecycle monitoring
- Performance metrics

### Documentation
Each module provides:
- Configuration schema documentation
- Event interface documentation
- Lifecycle hook reference
- Usage examples