Skip to content

Architecture Overview

Petfolio is built as an Nx monorepo with a modular architecture designed for scalability and maintainability.

System Architecture

graph TB
    subgraph "Applications"
        A[petfolio-business<br/>Next.js 16 App]
        B[petfolio-ui-tests<br/>Playwright E2E]
        C[petfolio-docs<br/>MkDocs Material]
    end

    subgraph "Shared Libraries"
        D[ui-component-library<br/>React Components]
        E[util-global-theme<br/>MUI Theme]
    end

    subgraph "Infrastructure"
        F[Docker Container]
        G[GitHub Pages]
        H[GitHub Actions CI/CD]
    end

    A --> D
    A --> E
    B --> A
    D --> E
    A --> F
    C --> G
    A --> H
    C --> H

Technology Stack

Frontend

Technology Version Purpose
Next.js 16.0.9 App Router, SSR, Server Components
React 19.2.1 UI framework
Material UI 7.3.6 Component library
TypeScript 5.9.2 Type safety
Emotion 11.14.0 CSS-in-JS

Build & Tooling

Technology Version Purpose
Nx 22.2.3 Monorepo orchestration
Jest 30.0.2 Unit testing
Playwright 1.36.0 E2E testing
ESLint 9.18.0 Linting
Storybook 10.1.3 Component documentation

Documentation

Technology Version Purpose
MkDocs Material 9.5+ Documentation site
Mike 2.1+ Version management
Mermaid - Diagrams

Module Organization

Apps Layer

Applications are end-user facing projects:

  • petfolio-business: Main Next.js application

    • App Router architecture
    • Server and client components
    • Cookie-based theme switching
    • Standalone build output for Docker

  • petfolio-ui-tests: E2E test suite

    • Playwright test framework
    • Multi-browser testing
    • Automated in CI pipeline

  • petfolio-docs: Documentation site

    • MkDocs Material theme
    • GitHub Pages deployment
    • Version control with Mike

Libs Layer

Shared libraries provide reusable code:

  • ui-component-library

    • Atomic design pattern (atoms → molecules → organisms)
    • Storybook integration
    • Comprehensive test coverage
    • Emotion styled components

  • util-global-theme

    • MUI theme configuration
    • Light/dark mode support
    • High contrast accessibility theme
    • Theme switching utilities

Design Patterns

Atomic Design

Components are organized hierarchically:

graph LR
    A[Atoms] --> B[Molecules]
    B --> C[Organisms]
    C --> D[Templates]
    D --> E[Pages]

    style A fill:#e1f5ff
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#29b6f6
  • Atoms: Basic building blocks (Button, Input, Icon)
  • Molecules: Simple combinations (SearchBar, FormField)
  • Organisms: Complex components (Header, ProductCard)
  • Templates: Page layouts
  • Pages: Actual routes in the app

Barrel Exports

Each library exposes a clean public API:

// libs/ui-component-library/src/index.ts
export * from './lib/atoms/Button/Button';
export * from './lib/molecules/SearchBar/SearchBar';

Consumers import via path aliases:

import { Button, SearchBar } from '@ui-component-library';

Theme Provider Pattern

Themes are provided at the root level:

// apps/petfolio-business/src/app/layout.tsx
import { ThemeProvider } from '@util-global-theme';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

Build Pipeline

sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub
    participant CI as GitHub Actions
    participant Nx as Nx Cloud
    participant Deploy as Deployment

    Dev->>Git: Push changes
    Git->>CI: Trigger workflow
    CI->>Nx: Detect affected projects
    Nx-->>CI: Return affected list
    CI->>CI: Lint, Test, Build (parallel)
    CI->>CI: Security scan (Trivy)
    CI->>Deploy: Deploy (if main branch)
    Deploy-->>Dev: Deployment complete

Build Optimization

Nx provides intelligent caching:

  1. Computation Cache: Reuses previous build results
  2. Affected Detection: Only builds changed projects
  3. Parallel Execution: Runs independent tasks concurrently
  4. Remote Caching: Shares cache across CI and developers (optional)

Security

Static Analysis

  • ESLint Security Plugin: Detects common vulnerabilities
  • No Unsanitized Plugin: Prevents XSS attacks
  • TypeScript Strict Mode: Catches type-related bugs

Container Security

  • Multi-stage builds: Minimal production images
  • Trivy scanning: Vulnerability detection in dependencies
  • Non-root user: Containers run with restricted privileges
  • Health checks: Automatic restart on failure

Dependency Management

  • Dependabot: Automated dependency updates
  • Version pinning: Exact versions in package-lock.json
  • Audit on CI: npm audit runs in pipeline

Performance

Next.js Optimizations

  • App Router: Automatic code splitting
  • Server Components: Reduced client bundle size
  • Standalone output: Optimized production builds
  • Image optimization: Built-in next/image

Build Performance

  • Nx cache: 10-100x faster repeat builds
  • Incremental builds: Only rebuild changed code
  • Parallel execution: Utilize all CPU cores

Authentication

!!! info "Coming Soon" Authentication architecture documentation will be added as the feature is implemented.

Planned features:

  • JWT-based authentication
  • Cookie storage for tokens
  • Server-side session validation
  • Social login integration

Next Steps