Forem: Jason Moody

Building a Portfolio That Actually Demonstrates Enterprise Skills - Part 3

Jason Moody — Thu, 08 Jan 2026 14:05:00 +0000

Phase 2: The Invisible Architecture

Core Services, Error Handling, and Authentication That Power Everything

In the previous article, I covered Phase 1, where I established the tooling and governance that set the rules of engagement for the entire project. With ESLint, Prettier, Vitest, Playwright, and CI/CD pipelines in place, the foundation was solid. Phase 2 builds on that foundation by implementing what I call the "invisible architecture," the singleton services, error handling, and authentication system that run underneath every feature without the user ever seeing them.

This is the code that separates production applications from demos. Anyone can build a login form. The difference is what happens when the network fails, when sessions expire, when errors cascade, and when the application needs to recover gracefully. Phase 2 addresses all of these concerns.

The Phase 2 specification breaks this work into four major areas: typed environment configuration, infrastructure services (logging, analytics, SEO, theming), global error handling, and authentication. Each area follows the same principle: abstract what might change behind clean interfaces.

The Philosophy: Abstractions That Enable Change

Before diving into implementation details, it's worth explaining the guiding principle behind Phase 2's architecture: abstract everything that might change.

In enterprise software, requirements change constantly. The analytics vendor you use today might be replaced next quarter. The authentication provider might switch from a mock implementation to OAuth to SAML. The logging service might need to pipe errors to Sentry instead of the console. If these concerns are hardcoded throughout the application, changing them requires touching dozens of files and risking regressions everywhere.

The solution is to define interfaces (contracts) and use Angular's dependency injection to swap implementations without changing consuming code. This is the Strategy Pattern, and it appears throughout Phase 2:

AuthStrategy defines what any authentication provider must do, whether it's a mock for demos or a real OAuth flow
AnalyticsProvider defines what any analytics service must implement, whether it's console logging or Google Analytics
Environment configuration is injected via tokens, not imported directly

┌─────────────────────────────────────────────────────────┐
│                    Application Code                     │
│         (Components, Services, Features)                │
└────────────────────┬────────────────────────────────────┘
                     │ depends on
                     ▼
         ┌───────────────────────┐
         │  Strategy Interface   │  (Contract: what must be done)
         │  - AnalyticsProvider  │
         │  - AuthStrategy       │
         └───────────┬───────────┘
                     │ implemented by (swappable)
        ┌────────────┴────────────┐
        ▼                         ▼
┌──────────────────┐    ┌──────────────────┐
│ Implementation A │    │ Implementation B │
│ (Mock/Console)   │    │ (Real/Google)    │
└──────────────────┘    └──────────────────┘
   Selected via             Selected via
   app.config.ts           app.config.ts

This approach adds a small amount of upfront complexity, but it pays dividends when requirements inevitably change. Swapping an analytics provider becomes a one-line change in app.config.ts rather than a refactoring project.

Typed Environment Configuration

The first piece of Phase 2 is typed environment configuration. Angular provides an environment file mechanism, but out of the box, there's no type safety. You can access environment.anything without the compiler complaining, even if that property doesn't exist.

The solution is a TypeScript interface that defines exactly what the environment must contain:

export interface AppEnvironment {url
  readonly appName: string;
  readonly production: boolean;
  readonly apiUrl: string;
  readonly features: FeatureFlags;
  readonly analytics: AnalyticsConfig;
  readonly version: string;
}

Every environment file must satisfy this interface. The compiler catches typos, missing properties, and type mismatches at build time rather than runtime. The readonly modifiers prevent accidental mutation of environment values, which should be immutable throughout the application lifecycle.

Rather than importing the environment file directly (which creates tight coupling), the configuration is provided via an injection token:

export const ENVIRONMENT = new InjectionToken<AppEnvironment>('ENVIRONMENT');Figure 3: Errors are caught at the network layer, transformed into user-friendly messages, and logged with context for debugging.

export function provideEnvironment(): Provider {
  return { provide: ENVIRONMENT, useValue: environment };
}

Services inject ENVIRONMENT rather than importing the file directly. This makes testing trivial since you can provide a mock environment in tests without any module gymnastics. It also means the environment source could change in the future without touching any consuming code.

Infrastructure Services

Phase 2 implements four infrastructure services that other parts of the application depend on. Each follows the same pattern: a clear interface, comprehensive logging, and thorough test coverage.

LoggerService: The Foundation of Observability

The simplest service is also one of the most important. LoggerService wraps console methods with environment-aware behavior. In development, all log levels output normally. In production, log() and info() are suppressed to avoid console noise, while warn() and error() always output.

This seems trivial, but it serves two purposes. First, it provides a single point where logging behavior can change. If the application later needs to send errors to Sentry or Datadog, only LoggerService needs modification. Second, it prevents the common mistake of leaving debug logs in production code. With the logger checking the environment, debug information never reaches production users' consoles.

The service is intentionally simple. Just 15 tests cover all the behavior. Sometimes the best code is the code that does exactly one thing well.

AnalyticsService: The Strategy Pattern in Action

Analytics demonstrates the Strategy Pattern clearly. The application needs to track events and page views, but the destination might be console logging during development, Google Analytics in production, or something else entirely.

The solution starts with an interface:

export interface AnalyticsProvider {
  readonly name: string;
  initialize(): Promise<void>;
  trackEvent(name: string, properties?: EventProperties): void;
  trackPageView(url: string, title?: string): void;
  identify(userId: string, traits?: EventProperties): void;
  reset(): void;
}

Two implementations exist: ConsoleAnalyticsProvider for development (logs everything via LoggerService) and GoogleAnalyticsProvider for production (integrates with GA4/gtag.js). The AnalyticsService acts as a facade, delegating to whichever provider is configured.

Switching providers is a one-line change in environment configuration:

analytics: {
  enabled: true,
  provider: 'google',  // or 'console'
  google: { measurementId: 'G-XXXXXXXXXX' }
}

The provideAnalytics() function reads this configuration and provides the appropriate implementation. An app initializer ensures the provider is ready before the application bootstraps. A separate withAnalyticsRouterTracking() provider automatically tracks page views on navigation events, so developers don't need to remember to add tracking to every route.

The total test count across all analytics code: 55 tests covering the service, both providers, and the router integration.

SeoService: Beyond Basic Meta Tags

SEO in modern applications goes far beyond setting a page title. Search engines and social platforms expect specific meta tags, Open Graph properties, Twitter Card metadata, and JSON-LD structured data. SeoService handles all of these concerns through a unified API.

The primary method accepts a comprehensive configuration object:

seo.updatePageSeo({
  title: 'How to Build Enterprise Angular Apps',
  meta: {
    description: 'A comprehensive guide to building...',
    keywords: ['angular', 'enterprise', 'architecture'],
  },
  canonicalUrl: '/blog/enterprise-angular',
  openGraph: {
    type: 'article',
    image: '/assets/images/article-cover.jpg',
  },
  twitterCard: {
    card: 'summary_large_image',
    creator: '@architect',
  },
  jsonLd: {
    '@type': 'Article',
    headline: 'How to Build Enterprise Angular Apps',
    datePublished: '2025-01-15',
  },
});

One method call sets the page title, description, keywords, canonical URL, Open Graph tags for Facebook and LinkedIn sharing, Twitter Card metadata, and JSON-LD structured data for rich search results. The service handles the DOM manipulation, creates and removes script tags for JSON-LD, and ensures proper cleanup on navigation.

This service required 49 tests to cover all the combinations of metadata and edge cases around tag cleanup.

ThemeService: System Preferences and Persistence

Figure 2: The theming engine supports multiple color schemes and high-contrast modes, persisted via LocalStorage.

Modern applications need to support light mode, dark mode, and often a "system" setting that follows the operating system preference. ThemeService implements this with signals for reactive state management.

The service tracks three things: the available themes, the currently active theme, and whether the theme was chosen explicitly or derived from system preferences. It watches the prefers-color-scheme media query and updates automatically when system preferences change. User preferences persist to localStorage and restore on subsequent visits.

Theme changes update a data-theme attribute on the document element, which CSS custom properties can target. This approach is simpler and more performant than maintaining theme state in JavaScript and passing it through the component tree.

I also included a script in the index.html.

    <script>
      (function () {
        var storageKey = 'theme-id';
        var defaultLight = 'light-default';
        var defaultDark = 'dark-default';

        // Check URL param first (for testing)
        var urlParams = new URLSearchParams(window.location.search);
        var themeParam = urlParams.get('theme');
        if (themeParam) {
          document.documentElement.setAttribute('data-theme', themeParam);
          return;
        }

        // Check localStorage
        var stored = localStorage.getItem(storageKey);
        if (stored) {
          document.documentElement.setAttribute('data-theme', stored);
          return;
        }

        // Fall back to system preference
        var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
        document.documentElement.setAttribute(
          'data-theme',
          prefersDark ? defaultDark : defaultLight,
        );
      })();
    </script>

Note that this script lives in index.html, outside of the Angular bootstrap process. This ensures it runs instantly when the DOM parses, preventing the dreaded 'flash of white light' that occurs if you wait for Angular to load before applying a dark theme preference.

The service includes 41 tests covering theme switching, system preference detection, persistence, and edge cases around initialization order.

Global Error Handling

Figure 3: Errors are caught at the network layer, transformed into user-friendly messages, and logged with context for debugging.

Error handling is where production applications diverge most sharply from demos. Demos assume everything works. Production applications assume everything can fail and plan accordingly.

The Error Handling Architecture

The error handling system has three layers:

GlobalErrorHandler catches any uncaught error in the Angular application
HttpErrorInterceptor catches and transforms HTTP errors into user-friendly messages
ErrorNotificationService provides a way to display errors to users (and will integrate with the toast system in Phase 3)

The GlobalErrorHandler extends Angular's ErrorHandler class. When an error occurs, it extracts useful information like the error message, stack trace, and component context, then logs it via LoggerService. The handler could also report errors to an external service like Sentry. It distinguishes between different error types and handles each appropriately, whether they're HTTP errors, chunk loading failures, or standard JavaScript errors.

One subtle but important detail: the handler checks for Error.cause, a relatively new JavaScript feature that allows errors to wrap underlying causes. Many frameworks now use this pattern, so properly extracting the root cause is essential for useful error messages.

HTTP Error Interception

The HttpErrorInterceptor transforms HTTP errors into consistent, user-friendly messages. A raw HttpErrorResponse might contain technical details that are useless to end users. The interceptor maps status codes to human-readable messages:

400: "The request was invalid. Please check your input."
401: "Your session has expired. Please log in again."
403: "You don't have permission to access this resource."
404: "The requested resource was not found."
429: "Too many requests. Please try again in X seconds."
500+: "A server error occurred. Please try again later."

For 429 (rate limiting) responses, the interceptor extracts the Retry-After header and includes the wait time in the error message. For 401 responses, it triggers the authentication store's session expiration flow, redirecting users to login.

The interceptor also logs errors appropriately. Network failures log differently than server errors, and each log entry includes relevant context like the HTTP method, URL, and status code.

Between the GlobalErrorHandler, HttpErrorInterceptor, and ErrorNotificationService, the error handling code has 77 tests covering every error type, edge case, and recovery scenario.

Authentication: The Most Critical System

Authentication is Phase 2's most complex system and demonstrates several patterns working together. The design uses the Strategy Pattern to support different authentication mechanisms, NgRx SignalStore for state management, and functional route guards for access control.

The Strategy Pattern for Auth

Authentication requirements vary wildly between applications. Some use simple username/password flows. Others use OAuth with external providers. Some need SAML for enterprise SSO. A demo application might use mock authentication with localStorage.

The solution is an interface that defines what any authentication strategy must do:

export interface AuthStrategy {
  readonly name: string;
  login(credentials: LoginCredentials): Observable<User>;
  logout(): Observable<void>;
  checkSession(): Observable<User | null>;
}

The interface is intentionally minimal. It doesn't prescribe how authentication works, only that any strategy must be able to login with credentials, log out, and check whether a valid session exists. This abstraction allows the mock implementation used during development to be swapped for a real OAuth implementation later without changing any consuming code.

MockAuthStrategy: Simulating Real-World Conditions

The mock implementation isn't just a stub that returns success. It simulates real-world conditions that the application must handle:

Network latency: Every operation includes an 800ms delay to simulate network round-trips
Random failures: In non-production environments, 10% of requests randomly fail to test error handling
Session persistence: Sessions store in localStorage with a JWT-like token structure
Multiple user types: Accepts "demo" (standard user) and "admin" (admin privileges) as usernames

These behaviors ensure the application handles loading states, error recovery, and different user roles correctly. Without them, it's easy to build an app that works perfectly in development but falls apart when network conditions are imperfect.

The mock strategy has 25 tests covering all login scenarios, logout behavior, session restoration, error simulation, and the differences between production and development modes.

AuthStore: Reactive State with SignalStore

Authentication state lives in an NgRx SignalStore. The store manages the current user, authentication status, loading states, and error messages. It exposes computed signals for derived state:

withComputed((store) => ({
  displayName: computed(() => store.user()?.username ?? 'Guest'),
  isAdmin: computed(() => store.user()?.roles.includes('admin') ?? false),
  hasRole: computed(() => (role: UserRole) => store.user()?.roles.includes(role) ?? false),
  avatarUrl: computed(() => store.user()?.avatarUrl ?? '/assets/images/default-avatar.svg'),
}));

These computed signals derive from the user state, so components can use authStore.displayName() or authStore.isAdmin() without manually checking for null users or extracting role information.

The store uses rxMethod from @ngrx/signals for operations that involve observables. The login, logout, and checkSession methods are reactive. They accept input (credentials or nothing), pipe through the authentication strategy, update state on success or failure, and handle side effects like navigation and logging.

A critical detail: the store integrates with the HTTP error interceptor. When a 401 response occurs, the interceptor calls authStore.handleSessionExpired(), which clears the user state and redirects to login. This ensures session expiration is handled consistently regardless of which HTTP request triggered it.

The store has 40 tests covering state management, login/logout flows, session restoration, error handling, and the session expiration integration.

Route Guards: Protecting Resources

Three functional guards control route access:

authGuard: Requires authentication. Redirects to /auth/login if not authenticated.
adminGuard: Requires admin role. Redirects to /forbidden if not admin.
guestGuard: Requires no authentication. Redirects to / if already authenticated (prevents logged-in users from seeing the login page).

The guards are simple functions that inject the AuthStore and check the appropriate signal:

export const authGuard: CanActivateFn = () => {
  const authStore = inject(AuthStore);
  const router = inject(Router);

  if (authStore.isAuthenticated()) {
    return true;
  }

  return router.createUrlTree(['/auth/login']);
};

Functional guards are a newer Angular pattern that replaces class-based guards. They're simpler, more testable, and align with Angular's move toward functional APIs.

The guards have 9 tests covering all access control scenarios.

Provider Registration

All authentication components register through a single provideAuth() function:

export function provideAuth(): EnvironmentProviders {
  return makeEnvironmentProviders([
    { provide: AUTH_STRATEGY, useClass: MockAuthStrategy },
    provideAppInitializer(() => {
      const authStore = inject(AuthStore);
      authStore.checkSession(undefined);
    }),
  ]);
}

This function provides the mock strategy and registers an app initializer that checks for an existing session on startup. The app initializer runs before Angular bootstraps the application, ensuring authentication state is ready before any components render. When a user refreshes the page, the initializer restores their session from localStorage, creating a seamless experience. Users stay logged in across page refreshes without seeing loading states or being kicked to the login page. This detail matters for perceived performance and user experience.

Swapping to a real authentication strategy later requires only changing which class is provided for AUTH_STRATEGY. Everything else continues working unchanged: the store, guards, and error handling integration all remain the same.

The Test Coverage Story

Phase 2 concludes with 318 unit tests across all services and components. Here's the breakdown:

Component	Tests
Environment Config	4
LoggerService	15
AnalyticsService	17
Analytics Providers	38
SeoService	49
ThemeService	41
GlobalErrorHandler	27
HttpErrorInterceptor	44
ErrorNotificationService	6
MockAuthStrategy	25
AuthStore	40
Auth Guards	9
App Component	3
Total	318

Every service has tests covering its public API, edge cases, error conditions, and integration points. The CI pipeline enforces 85% coverage thresholds, and the actual coverage exceeds that in most areas.

This test coverage isn't just a vanity metric. It provides confidence that the invisible architecture works correctly, enabling faster development in later phases. When a feature relies on AuthStore or SeoService, the feature developer doesn't need to worry about whether those services work. The tests already prove they do.

Lessons Learned

Building Phase 2 reinforced several lessons:

Abstractions require discipline. It's tempting to skip the interface and code directly against an implementation when you "only have one implementation." But the interface forces you to think about the contract, makes testing easier, and enables future flexibility. The small upfront cost is worth it.

Error handling is a feature. Users don't see error handling when it works. They just see an application that recovers gracefully. But they definitely notice when it fails. Investing in comprehensive error handling early prevents embarrassing production incidents later.

Mock implementations should be realistic. A mock that always succeeds instantly doesn't prepare the application for real-world conditions. Adding delays, random failures, and edge cases to mocks surfaces issues during development when they're cheap to fix.

SignalStore simplifies reactive state. Previous authentication implementations I've built used services with BehaviorSubjects, or full NgRx with actions and reducers. SignalStore hits a sweet spot. It's simpler than traditional NgRx but more structured than ad-hoc service state. The rxMethod pattern for async operations is particularly elegant. It effectively replaces the 'Service with a Subject' pattern that has dominated Angular for a decade. Instead of manually managing BehaviorSubject.next(), we just update the signal.

Comprehensive testing enables fearless refactoring. Several times during Phase 2, I refactored implementation details. I changed how errors were logged, restructured the auth flow, and adjusted how providers initialized. The tests caught regressions immediately, making refactoring safe rather than scary.

The foundation enables everything else. None of the work in Phase 2 is visible to end users, but all of it is essential for building features quickly and confidently. This invisible architecture is what makes the rest of the project possible.

What's Next

With Phase 2 complete, the application has a solid invisible architecture. Environment configuration is typed and injectable. Logging, analytics, SEO, and theming are abstracted behind clean interfaces. Errors are caught, transformed, and handled consistently. Authentication works with session persistence and route protection.

The next article will cover Phase 3, the Design System. That phase builds the visual component library with all the UI primitives that features will compose. With the core architecture in place, the design system can focus purely on presentation, knowing that services, state, and error handling are already solved.

You can explore the complete Phase 2 implementation on GitHub: MoodyJW/angular-enterprise-blueprint

Next in series: Phase 3 Deep Dive – The Design System and Component Library

Building a Portfolio That Actually Demonstrates Enterprise Skills - Part 2

Jason Moody — Thu, 01 Jan 2026 18:13:27 +0000

Phase 1: Building the Enterprise Rig

Tooling, Governance, and the Foundation That Makes Everything Else Possible

In the previous article, I outlined my approach to building a portfolio that demonstrates enterprise-level skills. The core idea is simple: treat a personal project with the same rigor you would apply to production software. That starts with Phase 1, which I call the "Enterprise Rig." This is the foundation of tooling, governance, and automation that everything else builds upon.

Before writing a single line of feature code, I spent time establishing the rules of engagement. Linting, formatting, testing, documentation, and CI/CD pipelines all needed to be in place. The principle guiding this phase is "shift left," meaning we catch (most) errors, style violations, and bad commits on the developer's machine before they ever reach the CI server or, worse, production.

This article explains the decisions I made during Phase 1, why I made them, and what I learned along the way.

Workspace Configuration: Starting Strict

Angular 21 ships with sensible defaults, but enterprise projects need stricter constraints. The first decision was enabling every strictness option available.

In angular.json, strict mode is enabled globally. This turns on strict template type checking, strict property initialization, and other TypeScript strictness flags. These settings catch entire categories of bugs at compile time that would otherwise surface at runtime. The short-term cost is that you write slightly more explicit code. The long-term benefit is that refactoring becomes safer and the codebase stays maintainable as it grows.

I also changed the component selector prefix from the default app to eb (Enterprise Blueprint). This prevents naming collisions if someone integrates these components into another project, and it makes it immediately clear which components belong to this codebase when reading templates.

For styling, I chose SCSS over plain CSS. The decision was practical: SCSS offers variables, nesting, and mixins that make maintaining a design system significantly easier. When you are building a component library with multiple themes, plain CSS becomes unwieldy quickly. Not to mention, SCSS is the de facto standard for Angular projects.

Package management uses npm with engine constraints in package.json. The project requires Node 20+ and npm 10+. This prevents developers from accidentally running the build with outdated tooling that might produce subtly different results. Version mismatches across a team are a common source of "works on my machine" problems, and engine constraints eliminate that class of issues entirely. I highly recommend using Node Version Manager (nvm) to manage Node versions if you find yourself working on multiple projects with different Node versions.

ESLint: The Flat Config and Architectural Boundaries

ESLint configuration was one of the more interesting parts of Phase 1. The JavaScript ecosystem recently shifted from the legacy .eslintrc format to the new "flat config" format. I decided to use flat config from the start rather than dealing with a migration later. Although I did end up (accidentally) using the deprecated tseslint config() as opposed to defineConfig(), but this will change in the future.

The flat config format uses eslint.config.mjs and exports an array of configuration objects. Each object can target specific file patterns, extend other configs, and define rules. The mental model is cleaner than the legacy format's cascading inheritance, and it plays better with TypeScript tooling.

The configuration extends typescript-eslint's strict type-checked preset along with Angular ESLint's recommended rules. This combination enables rules that require type information, like no-floating-promises (catching unhandled promise rejections) and no-misused-promises (preventing promises in places that expect synchronous code). These rules have caught real bugs in my professional work.

Beyond the standard rules, I added several strict TypeScript rules that I consider non-negotiable for enterprise code:

no-explicit-any prevents the any type entirely. If you need to represent an unknown type, use unknown and narrow it properly. I've had nightmares dealing with any types in the past.
explicit-function-return-type requires return type annotations on functions. This catches cases where TypeScript infers a broader type than you intended.
strict-boolean-expressions prevents truthy/falsy coercion in conditions. You must explicitly check for null, undefined, empty strings, or zero.
no-unnecessary-condition catches conditions that are always true or always false based on the types.

These rules add friction when writing code, but they eliminate entire categories of subtle bugs. The investment pays off quickly on any project that will be maintained over time.

The most important plugin is eslint-plugin-boundaries. This plugin enforces architectural layering at the import level. The configuration defines five element types: entry points, app root files, core modules, features, and shared modules. Then it defines rules about which types can import from which:

Entry points (like main.ts) can only import from app root files
App root files can import from anywhere
Core modules can import from other core modules and shared
Features can import from core, shared, and the same feature, but not from other features
Shared can only import from other shared modules

That last rule is critical. Features cannot import from other features. This prevents the spaghetti dependencies that make large codebases unmaintainable. If two features need to share logic, that logic must move to shared or core. The boundaries are enforced automatically on every lint run, which means they cannot be accidentally violated during a rushed PR. Teams often use tools like Nx to enforce these boundaries, but I prefer to keep the configuration simple and focused on code quality.

For HTML templates, the configuration extends Angular ESLint's template accessibility rules. These catch common accessibility issues like missing alt text, improper ARIA usage, and form elements without labels. Accessibility enforcement at the linting level means these issues are caught before code review, not during manual QA. One common mistake I should have included earlier was checking the hierarchy of headings to ensure proper nesting, but I did not consider it until I was optimizing near the end of the project. I ended up adding it to the configuration in the final phase using a custom rule and also including markdown linting with markdownlint-cli2.

Prettier and Import Organization

Formatting is handled by Prettier with a simple configuration: single quotes, trailing commas, 2-space indentation, and a 100-character line width. The specific choices matter less than the consistency. Every file in the repository follows the same formatting rules, which eliminates bike-shedding in code reviews and makes diffs cleaner.

The prettier-plugin-organize-imports plugin automatically sorts and groups imports on every format. This eliminates manual import organization and ensures imports follow a consistent pattern across the codebase. It also removes unused imports automatically, which keeps files clean.

The integration with ESLint is intentionally minimal. Prettier handles formatting, ESLint handles code quality. Mixing the two leads to conflicts and slower lint runs. The configuration runs them separately: ESLint with --fix for auto-fixable issues, then Prettier for formatting.

Git Hooks: Enforcing Quality Before Commit

Husky manages Git hooks with two key hooks configured: pre-commit and commit-msg.

The pre-commit hook runs lint-staged, which executes linting and formatting only on staged files. This keeps the hook fast even in large codebases. For TypeScript and HTML files, it runs ESLint with auto-fix followed by Prettier. For SCSS, JSON, Markdown, and JavaScript config files, it runs only Prettier. The staged files are automatically re-staged after fixes, so the commit includes the corrected versions.

The commit-msg hook runs Commitlint to enforce conventional commit messages. Every commit must start with a type (feat, fix, docs, refactor, etc.) followed by a scope and description. This convention enables automated changelog generation in Phase 6 and makes the Git history readable. When you can scan commit messages and understand what changed without reading diffs, code archaeology becomes much easier. I can't say I followed this standard very well in the early stages, but I did follow it in the later parts of the project.

The combination of these hooks means that by the time code reaches the remote repository, it has already passed linting, formatting, and commit message validation. The CI pipeline rarely fails for style issues because those issues never make it past the developer's machine.

Testing: Vitest for Units, Playwright for E2E

Angular historically shipped with Karma and Jasmine for unit testing. Starting with Angular 21, the framework includes Vitest as the default test runner.

I stuck with Vitest for unit testing. Vitest is fast, has excellent TypeScript support, and provides a better developer experience than Karma. The watch mode is nearly instant, the error messages are clearer, and the configuration is simpler. It uses the same configuration format as Vite, which means less tooling to learn.

The Vitest configuration is straightforward. It uses jsdom for DOM simulation, includes verbose and JUnit reporters (the latter for CI integration), and targets *.spec.ts files in the src directory. Coverage uses the v8 provider with thresholds set at 85% for statements, branches, functions, and lines. The CI pipeline fails if coverage drops below these thresholds, which prevents coverage from slowly eroding over time.

For end-to-end testing, Playwright was the obvious choice. It supports Chromium, Firefox, and WebKit from a single API, runs tests in parallel, and has excellent debugging tools. The Playwright test runner is also significantly faster than alternatives like Cypress because it does not run tests inside a browser's JavaScript context. Being free and open source is another big plus.

The E2E configuration enables sharding for CI. The dedicated E2E workflow splits tests across four parallel runners using Playwright's built-in sharding support. Each shard runs a quarter of the tests, and the results are uploaded as separate artifacts. This approach scales well as the test suite grows, and it keeps CI times reasonable even with comprehensive E2E coverage.

CI/CD: GitHub Actions Workflows

The CI/CD setup uses multiple GitHub Actions workflows, each with a specific responsibility.

The main CI workflow runs on every push to main and every pull request. It has four jobs that run in parallel where possible: lint, test, build, and E2E. The lint job runs ESLint and checks Prettier formatting. The test job runs Vitest with coverage and uploads results to Codecov. The build job creates a production build and uploads it as an artifact. The E2E job depends on the build job, downloads the artifact, and runs Playwright tests against it.

All workflows use npm caching through the setup-node action, which significantly speeds up dependency installation. The concurrency setting cancels in-progress runs when a new commit is pushed to the same branch, preventing resource waste on outdated commits.

The dedicated E2E workflow runs Playwright with sharding across four parallel machines. Each machine installs dependencies, installs Playwright browsers, runs its shard of tests, and uploads the report. The fail-fast: false setting ensures all shards complete even if one fails, which gives complete test results rather than stopping at the first failure.

Security scanning uses GitHub's CodeQL on a weekly schedule and on every PR. CodeQL analyzes TypeScript code for common vulnerabilities like XSS and injection attacks. The dependency review workflow scans package-lock.json changes and blocks PRs that introduce dependencies with high-severity common vulnerabilities and exposures (CVEs) or non-compliant licenses.

The deployment workflow triggers on pushes to main, which isn't ideal for a large codebase, but served my purposes well. It builds the Angular application, Storybook, and Compodoc documentation, then merges them into a single artifact and deploys to GitHub Pages. The Storybook build ends up at /storybook and the API documentation at /docs, making all project documentation accessible from a single deployment. Eventually I will include links directly to the documentation from the main page.

Lighthouse CI runs on pull requests to catch performance regressions before they merge. This ensures bundle size stays reasonable and performance metrics do not degrade over time. This is the longest running CI pipeline, but it checks all six themes and all pages of the application. At first, Lighthouse scores below 90 were considered a failure, but later I bumped the thresholds for accessibility, SEO, and best practices to 100 and left performance at 90.

Documentation: Storybook and Compodoc

Documentation is treated as code in this project. That means it lives in the repository, builds automatically, and deploys alongside the application.

Storybook serves as the visual catalog for the design system. It targets the src/app/shared directory where all reusable UI components live. Each component gets a .stories.ts file that demonstrates its variants, states, and props. The Storybook configuration uses Angular's application builder and enables automatic documentation generation.

Storybook's accessibility addon runs axe-core checks on every story, which catches accessibility issues during component development rather than after integration. When you can see accessibility violations in the Storybook UI while building a component, fixing them becomes part of the natural workflow rather than a separate QA step.

Compodoc generates API documentation from TSDoc comments in the code. It targets core services and feature modules, producing documentation that includes dependency graphs, method signatures, and cross-references. The configuration excludes test and story files to keep the documentation focused on production code.

Both tools build as part of the deployment workflow and are accessible from the deployed site (in-app Storybook / Compodoc). This means stakeholders can browse component documentation and API references without running the project locally.

Internationalization: Why Transloco

For internationalization, I chose Transloco over Angular's built-in @angular/localize. The decision came down to workflow and flexibility.

Angular's localize requires building separate bundles for each language. This approach offers better runtime performance because translations are compiled into the bundle, but it complicates the build and deployment pipeline. You need separate deployments for each language or a server that routes to the correct bundle.

Transloco uses runtime translation loading. The application builds once, and translation files load via HTTP based on the selected language. This means a single deployment supports all languages, and adding a new language is just adding a JSON file. Language switching is instant without a page reload, which provides a better user experience for applications where users might switch languages frequently.

The Transloco configuration sets English as the default language with Spanish and eventually French as additional options. Translation files live in assets/i18n/ as JSON files with dot-notation keys that mirror the component structure. This naming convention makes it easy to find and update translations for specific features.

For this portfolio project, the simpler deployment workflow and instant language switching outweigh the marginal performance benefits of build-time localization. If the application needed to support dozens of languages or had strict performance requirements, the calculus might be different.

Lessons Learned

Phase 1 took longer than I initially expected, but the investment will likely pay off long-term (it absolutely did).

The boundaries plugin will catch architectural violations during later phases that I probably would have overlooked. Having the tooling enforce architecture rather than relying on discipline and documentation makes a real difference. This matters even more when developing with AI-assisted tools like GitHub Copilot or Claude. LLMs can generate valid-looking code that violates architectural boundaries or uses implicit type coercion. Having automated linting catch these mistakes immediately means you can move fast with AI assistance while maintaining code quality; the tooling acts as a safety net that catches errors whether they come from human developers or AI suggestions.

The strict TypeScript rules caused friction initially, but they caught real bugs. The strict-boolean-expressions rule in particular surfaced several places where I was relying on implicit coercion that could have caused issues with falsy values like zero or empty strings.

Setting up Vitest with Angular was smoother than I expected. In previous projects, I struggled with configuration issues and slow test runs. This time, the setup worked on the first try and tests run fast enough that I actually run them frequently during development.

The CI pipeline catches issues before they become problems. I have pushed commits that broke the build or failed linting, and the feedback loop is fast enough that I catch and fix these issues before context-switching to something else.

What's Next

With Phase 1 complete, the project has a solid foundation of tooling and automation. The next article will cover Phase 2: Core Architecture. That phase builds the invisible infrastructure that powers the application, including environment configuration, core services, error handling, and the mock authentication system.

The patterns established in Phase 1 will guide development throughout the remaining phases. Every new file gets linted and formatted automatically. Every commit follows conventional commit standards. Every PR must pass the quality gates. This consistency compounds over time, making the codebase easier to maintain as it grows.

You can explore the complete Phase 1 implementation on GitHub: MoodyJW/angular-enterprise-blueprint

Next in series: Phase 2 Deep Dive - Core Architecture, Services, and Authentication

Building a Portfolio That Actually Demonstrates Enterprise Skills - Intro

Jason Moody — Mon, 29 Dec 2025 14:54:30 +0000

Creating an Enterprise Blueprint as a Portfolio Using Angular

As a Lead Front-end Developer, I don't have much time for personal projects, and none of my professional work is public. I realized I needed something tangible to demonstrate my skills. Instead of building a collection of small projects, I'm creating a "mini enterprise" application as my portfolio. This means applying modern architecture, documentation standards, CI/CD pipelines, comprehensive testing, and other common enterprise practices. I'm treating it like a real production project, following enterprise best practices from the ground up. This approach lets me focus on a single project while demonstrating an entire professional skill set.

In this introductory article, I'll explain the motivation behind this approach, outline the technology decisions, and provide a roadmap of what's to come. Future articles will dive deep into each phase of implementation.

The Problem with Traditional Developer Portfolios

Most developer portfolios fall into one of two traps: either they're visually polished static sites that lack technical depth, or they're collections of small demos that show variety but not complexity. Neither format reflects what it's like to build and maintain enterprise-scale software.

Consider what a typical portfolio might include: a to-do app, a weather widget, maybe a simple e-commerce page. These projects demonstrate basic competency, but they don't show how you handle the challenges that define senior-level work. How do you structure a codebase that multiple developers can maintain? How do you enforce code quality across a team? How do you ensure accessibility compliance? How do you set up deployment pipelines that catch bugs before they reach production?

As someone working on proprietary enterprise applications, I face a specific challenge. My daily work involves complex state management, routing architectures, comprehensive test suites, and CI/CD automation; however, none of that code can be shared publicly. I needed a way to showcase these skills without violating NDAs or exposing proprietary code.

The solution was to build something new that demonstrates the same principles and practices I use professionally, but in a context I can share openly.

The "Mini Enterprise" Approach

Rather than build many small apps, I decided to build one portfolio application that mirrors how enterprise teams operate. That means treating it as a serious product with production-grade standards, not a weekend side project.

The goal is to create something that functions as both a personal portfolio and a "clone-and-go" starter kit for enterprise teams. Anyone should be able to clone the repository and have a fully functional development environment with all the tooling, testing, and CI/CD infrastructure already configured.

Here's what that looks like in practice:

Figure 1: Automated quality gates enforcing standards on every Pull Request.

Infrastructure First: Before writing any feature code, I built out the complete development foundation. That includes ESLint with strict type checking and accessibility rules, automated testing with Vitest and Playwright, documentation through Storybook and Compodoc, and Git hooks to enforce code quality before commits even reach the repository. I also leveraged AI tools like GitHub Copilot and Claude to help scaffold boilerplate, generate initial test stubs, and accelerate repetitive setup tasks, freeing me to focus on architecture and quality decisions.

In enterprise development, you don't start building features until the base infrastructure is solid. This "shift left" philosophy catches errors, style violations, and problematic commits on the developer's machine before they ever reach the CI server.

Architecture Over Aesthetics:

Figure 2: The strict unidirectional data flow: Features consume Core and Shared, but never each other.

While the portfolio will look professional, the emphasis is on maintainable architecture. It's built with Angular 21 using standalone components, signals for reactive state management, NgRx SignalStore for centralized state, and lazy-loaded routes for performance. The codebase follows a strict layered architecture: Core services (singletons loaded once), Shared components (reusable UI elements), and feature modules (routed pages). ESLint rules enforce these boundaries, features cannot import from other features, and shared components cannot depend on core services.

Each architectural decision is documented with clear rationale. When someone reviews the codebase, they should understand not just what was built, but why it was built that way.

Quality Gates: Nothing merges without passing quality checks. The CI/CD pipeline runs linting, unit tests with 85% coverage thresholds, E2E tests across multiple browsers, security scanning with CodeQL, dependency vulnerability checks, and Lighthouse performance audits. If any of these checks fail, the pull request cannot be merged. This mirrors how enterprise teams operate. Quality is enforced automatically, not left to manual review.

Accessibility as a Requirement: The project targets WCAG 2.1 AA compliance as a minimum, with efforts toward AAA where practical. This includes proper color contrast ratios, complete keyboard navigation, accurate ARIA labeling, and automated accessibility testing at multiple layers. Accessibility is built into the development process from the start, not retrofitted after the fact. The ESLint configuration includes Angular's template accessibility rules, and Storybook integrates accessibility auditing for every component.

Real-World Complexity: The app includes engineering elements that rarely appear in portfolio projects but define real enterprise work. There's proper error handling with a global error boundary and HTTP interceptors. Loading states are handled consistently across the application. Internationalization is set up with Transloco, supporting multiple languages with lazy-loaded translation files. A mock API layer simulates network latency and occasional failures, demonstrating how the application handles real-world conditions. These details separate production-ready code from demo code.

Planning Before Building: The Implementation Plan

Before writing code, I created an in-depth implementation plan that divides the work into six phases, each with clear deliverables, technical specifications, and success criteria. This isn't a static document, it's a set of living specifications that evolve as the project progresses.

Phase 1: Tooling and Governance – This phase establishes the "rules of engagement" for the entire project. It covers workspace configuration with Angular CLI in strict mode, ESLint with the boundaries plugin for architectural enforcement, Prettier with automatic import organization, Husky for Git hooks, Commitlint for conventional commit messages, Vitest for unit testing, Playwright for E2E testing, Storybook for component documentation, Compodoc for API documentation, and GitHub Actions workflows for CI/CD, security scanning, and deployment. The principle here is "shift left" and catch problems as early as possible in the development process.

Phase 2: Core Architecture – This phase builds the invisible singletons that power the application. It includes typed environment configuration, infrastructure services (logging, analytics, SEO, theming), global error handling with custom error boundaries and HTTP interceptors, and a mock authentication system. The authentication layer uses a strategy pattern, making it easy to swap the mock implementation for a real authentication provider later. NgRx SignalStore manages authentication state, with functional guards protecting routes.

Phase 3: The Design System – This phase develops the reusable UI component library that lives in the shared folder. It covers global styling with CSS custom properties supporting multiple themes (light, dark, high contrast), atomic components (buttons, icons, badges, spinners, cards), molecular components (alerts, breadcrumbs), layout components (containers, grids, stacks), form components with proper ControlValueAccessor implementation, and feedback components (toasts, modals, skeletons). Every component gets a Storybook story with documentation and accessibility checks.

Phase 4: The Application Shell – This phase builds the frame that holds all the pages. It includes the main layout component with header, footer, and router outlet, responsive navigation with theme picker integration, and lazy-loaded routing configuration. The header connects to the authentication store to show appropriate UI based on login state.

Phase 5: Feature Implementation – This phase creates the actual content of the portfolio. Features map one-to-one with UI navigation: a dashboard showing system status and build information, a "Reference Modules" catalog (the projects showcase), an "Architecture Decisions" viewer for ADRs, a profile page ("The Architect"), and a contact form ("Hire Me") with rate-limiting simulation. Each feature uses SignalStore for state management and includes its own documentation.

Phase 6: Ops and Optimization – This final phase ensures the application ships like enterprise software. It covers deployment to GitHub Pages, performance tuning with bundle budgets and Lighthouse CI, release management with automated changelog generation, and final documentation including a comprehensive README, contributing guide, and architecture overview.

Each phase builds on the previous one, just like a real enterprise project where you can't skip ahead without a solid foundation.

Why This Matters

When a hiring manager or technical lead reviews this portfolio, they won't just see a polished website. They'll see evidence of engineering discipline:

A Clean Git History: Commits follow conventional commit standards (feat, fix, docs, refactor, etc.), enabling automated changelog generation. The history tells a story of incremental, well-documented progress.

Architectural Documentation: Architecture Decision Records (ADRs) capture the reasoning behind significant technical choices. This demonstrates not just the ability to make decisions, but the ability to communicate and document them for future team members.

Measurable Test Coverage: Test coverage isn't assumed, it's enforced. The CI pipeline fails if coverage drops below 85%. Unit tests use Vitest for speed, and E2E tests use Playwright for cross-browser validation.

DevOps Proficiency: The GitHub Actions workflows demonstrate understanding of CI/CD pipelines, including build optimization, test parallelization, security scanning, and automated deployment.

Accessibility Compliance: Automated accessibility testing at the linting, component, and E2E levels proves attention to inclusive design. This is increasingly important for enterprise applications that must meet legal accessibility requirements.

Strict TypeScript Discipline: The entire codebase uses strict TypeScript with zero any types. ESLint rules enforce explicit return types, proper null handling, and other type safety best practices.

This is what separates experienced engineers from those still building foundational skills. It's not about knowing the latest framework, but about demonstrating engineering discipline, maintainability, and attention to the details that matter in production systems.

The Technology Stack

I chose Angular 21 because it offers enterprise-grade features out of the box: standalone components that simplify module management, fine-grained reactivity via signals, built-in dependency injection, and a mature ecosystem with excellent tooling. It's designed for building large-scale, maintainable applications—exactly what this project aims to demonstrate.

Core Framework: Angular 21 with standalone components, TypeScript 5.9 in strict mode, RxJS for async operations, Signals for reactive state, and NgRx SignalStore for centralized state management.

Testing: Vitest for unit testing (fast, modern, excellent developer experience), Playwright for E2E testing across Chromium, Firefox, and WebKit, with support for visual regression testing.

Code Quality: ESLint with Angular ESLint rules, the boundaries plugin for architectural enforcement, strict TypeScript rules, and 85% minimum coverage thresholds.

Documentation: Storybook for visual component documentation with accessibility auditing, Compodoc for API documentation with dependency graphs, and TSDoc comments throughout the codebase.

Accessibility: WCAG 2.1 AA compliance as a baseline, with Angular's template accessibility linting and Storybook's a11y addon for component-level testing.

Build and Tooling: Angular CLI with the modern build system, npm for package management with engine version enforcement, Husky for Git hooks, and Prettier for consistent formatting.

CI/CD and Deployment: GitHub Actions for automated pipelines, CodeQL for security scanning, Lighthouse CI for performance auditing, and GitHub Pages for hosting.

Each tool was chosen for a specific reason: it solves a real problem or aligns with patterns I've seen succeed in enterprise environments. The stack is opinionated but practical; these are tools that work well together and scale to larger teams and codebases.

What's Next

This is the first post in a series documenting the entire process of building this portfolio. I'm not just writing tutorials, I'm sharing the reasoning, trade-offs, and lessons that arise from building a production-grade Angular application from scratch.

The next article will cover Phase 1 in depth: Tooling and Governance. I'll explain how I configured ESLint with the flat config format and boundaries plugin, set up Vitest to replace Karma and Jasmine, integrated Playwright for E2E testing, established Git hooks with Husky and Commitlint, configured Storybook and Compodoc for documentation, and built out the GitHub Actions workflows that enforce quality on every pull request.

If you're a developer aiming to demonstrate enterprise-level skills, preparing for senior or lead roles, or just interested in seeing how production-grade Angular projects are structured, I hope this series offers both practical insight and inspiration. If you have questions, suggestions, or your own experiences to share, I'd love to hear from you in the comments.

You can follow along with the project on GitHub: MoodyJW/angular-enterprise-blueprint

Next in series: Phase 1 Deep Dive – Infrastructure, Linting, Testing, and CI/CD Automation