How moodyjw/angular-enterprise-blueprint works
1. Overall shape
This is an Angular 21 single-page application organized as a strict layered frontend architecture. The runtime is browser-based; there is no dedicated backend in this repo. Most “data” comes from static assets, mock strategies, or external public APIs/services.
2. Bootstrap and application shell
src/main.ts bootstraps the app through src/app/app.config.ts, app.routes.ts, and the root app.ts/app.html component. The shell is responsible for global layout and route mounting, while feature pages are loaded lazily through Angular routing.
3. Layered dependency boundary
The repo explicitly enforces:
- core: application singletons and cross-cutting infrastructure
- features: routed domain pages, isolated from each other
- shared: reusable UI/components/utilities with no knowledge of core/features
This boundary is a major architectural constraint and should appear on any diagram.
4. Core subsystem
src/app/core contains app-wide services and policy layers: auth, configuration, error handling, i18n loader/config, HTTP interceptors, analytics, SEO, logging, theme management, storage/security, and preload strategy. These are instantiated once and then consumed by routes/features.
5. Authentication flow
Auth is strategy-based. The MockAuthStrategy in core stands in for a backend identity provider, with guards (auth.guard, guest.guard) protecting routes. Features like auth/login consume this core auth layer, but feature-to-feature auth coupling is intentionally avoided.
6. Feature modules
src/app/features contains the routed business areas: home, blog, contact, modules, profile, architecture, and auth. Each feature has its own component(s) plus local service/state files, typically using SignalStore-style state management. Features are intended to be lazy-loaded and self-contained.
7. Feature data sources
Several features are backed by static or semi-static content in src/assets/data and src/assets/docs:
- blog articles and blog metadata
- architecture/module JSON data
- ADR documents and markdown content
- i18n dictionaries in src/assets/i18n
This means the app behaves more like a content-driven portfolio/blueprint than a CRUD app.
8. Shared design system
src/app/shared is a large UI library of reusable, standalone components and utilities: buttons, cards, form controls, tabs, toast, tooltip, modal, layout primitives, theme picker, language switcher, etc. Storybook stories are present for many components, so the shared layer is a separately documented design system rather than just helper widgets.
9. Cross-cutting runtime services
Several core services influence user-facing behavior across features:
- Theme service toggles among accessible theme variants from src/styles/themes
- Transloco handles multilingual text loading
- Analytics service/providers route events to either console or Google Analytics
- SEO service manages metadata
- Global error handling converts runtime and HTTP failures into notifications/toasts
- CSRF/security services/interceptors prepare HTTP requests for secure APIs when used
These are cross-cutting concerns rather than feature logic.
10. Layout and navigation
Core layout components (header, footer, main-layout) form the persistent chrome around routed content. Shared navigation-related UI (user menu, nav dropdown, breadcrumb, language/theme controls) connects shell state to route context and user preferences.
11. Tooling, docs, and verification pipeline
The repo is built around strong quality gates: Vitest unit tests, Playwright E2E, Storybook, Compodoc docs, ESLint/Prettier/Commitlint, Lighthouse CI, and CodeQL. GitHub Actions handle CI, dependency review, release automation, deployment, and performance audits. The architecture is therefore not just code structure, but also a delivery pipeline that validates boundaries, accessibility, performance, and security.
12. Diagramming hint
A useful architecture diagram would show:
- browser entry → app bootstrap → shell/layout → lazy-loaded features
- features → core services/stores/interceptors
- features/shared UI → static assets/i18n/data
- core cross-cutting services → analytics, SEO, theme, auth, error notification
- external outputs → GitHub Pages deployment, Storybook/docs, analytics provider, optional public APIs
Main entry points: app.routes.ts Routes · components UI kit · app.config.ts App config · services Core services
Components 24
Runtime
Browser entry, bootstrap, routing, and shell
- main.ts · Browser entry point that starts Angular and wires app config
src/main.ts - App config · Provides application-wide providers and startup wiring
src/app/app.config.ts - Routes · Top-level route map with lazy feature loading
src/app/app.routes.ts - App shell · Root component and template that host the global layout
src/app/app.ts
Core
Singleton services, policy, and cross-cutting infrastructure
- Layout · Persistent header, footer, and main layout around routed content
src/app/core/layout - Auth · Strategy-based auth, guards, and auth state
src/app/core/auth - Core services · Analytics, architecture data, logging, security, SEO, storage, and theme services
src/app/core/services - i18n · Transloco loader and configuration for multilingual content
src/app/core/i18n - Interceptors · HTTP error and CSRF request handling
src/app/core/interceptors - Errors · Global error handler and notification bridge
src/app/core/error-handling
Features
Lazy routed business areas
- Home · Landing/dashboard routed feature with local state and service
src/app/features/home - Blog · Blog list and detail pages backed by static article data
src/app/features/blog - Modules · Module listing and detail views backed by JSON content
src/app/features/modules - Profile · Profile and stats view with feature-local state and service
src/app/features/profile - Architecture · Architecture and ADR viewer driven by authored docs/data
src/app/features/architecture - Login · Guest-facing login screen that consumes core auth
src/app/features/auth - Contact · Contact page with local state and service integration
src/app/features/contact
Shared
Reusable UI, services, and utilities
- UI kit · Reusable standalone components, controls, and navigation primitives
src/app/shared/components - Shared services · Toast and unique-id helpers used across the UI
src/app/shared/services - Utilities · Generic debounce, throttle, and validation helpers
src/app/shared/utilities
Content
Static assets and authored content
- Static content · JSON, markdown, i18n, docs, images, and resume assets
src/assets - Themes · Theme tokens and accessible color variants
src/styles/themes
Delivery
Tests, docs, Storybook, and CI
- CI/CD · GitHub Actions workflows for test, deploy, security, and release
.github/workflows - Quality tools · Vitest, Playwright, Storybook, ESLint, Lighthouse, and docs tooling
package.json
Connections 36
- main.ts → App config: boots · Main initializes the app through shared configuration
- App config → Routes: registers · App config provides routing and feature loading
- App config → Auth: provides · Registers auth and route-guard infrastructure
- App config → Core services: provides · Wires singleton app services and policies
- App config → i18n: provides · Sets up translation loading and locale config
- App config → Interceptors: provides · Installs HTTP policy layers
- App config → Errors: provides · Connects global error handling
- App shell → Layout: uses · Root shell renders persistent chrome
- Routes → Home: lazy loads · Primary routed landing feature
- Routes → Blog: lazy loads · Blog routes are loaded on demand
- Routes → Modules: lazy loads · Modules routes are loaded on demand
- Routes → Profile: lazy loads · Profile routes are loaded on demand
- Routes → Architecture: lazy loads · Architecture routes are loaded on demand
- Routes → Login: lazy loads · Auth routes are loaded on demand
- Routes → Contact: lazy loads · Contact routes are loaded on demand
- Login → Auth: consumes · Login screen uses core auth strategy and guards
- Home → Core services: consumes · Dashboard feature pulls from core services and stores
- Blog → Static content: reads · Blog content comes from static JSON and markdown
- Modules → Static content: reads · Module catalog is driven by static JSON content
- Profile → Core services: consumes · Profile feature uses core data and runtime services
- Architecture → Static content: reads · Architecture viewer reads docs and architecture data
- Contact → Core services: consumes · Contact feature uses shared runtime services
- Layout → UI kit: composes · Shell chrome is built from reusable UI primitives
- Home → UI kit: uses · Features compose shared UI components
- Blog → UI kit: uses · Blog pages use shared cards, lists, and navigation UI
- Modules → UI kit: uses · Modules pages use shared display and navigation controls
- Profile → UI kit: uses · Profile view uses reusable cards and charts
- Contact → UI kit: uses · Contact page uses form and feedback components
- Architecture → UI kit: uses · Architecture viewer uses shared reading and layout UI
- UI kit → Shared services: depends on · UI components rely on toast and identifier helpers
- UI kit → Themes: styled by · Shared components consume the theme system
- Core services → Themes: toggles · Theme service switches accessible theme variants
- Core services → Static content: sources · Architecture, analytics, and content services read static assets
- i18n → Static content: loads · Translation dictionaries are stored in assets
- Errors → Shared services: notifies · Errors are surfaced through shared toast behavior
- CI/CD → Quality tools: gates · CI workflows run tests, linting, docs, E2E, and audits