Assist_Design/apps/portal/ARCHITECTURE.md

Portal Architecture

This document outlines the new feature-driven architecture implemented for the customer portal.

Folder Structure

apps/portal/src/
├── app/                    # Next.js App Router pages
├── components/             # Shared UI components (Design System)
│   ├── ui/                 # Base UI components (atoms)
│   ├── layout/             # Layout components (organisms)
│   └── common/             # Shared business components (molecules)
├── features/               # Feature-specific modules
│   ├── auth/               # Authentication feature
│   ├── dashboard/          # Dashboard feature
│   ├── billing/            # Billing feature
│   ├── subscriptions/      # Subscriptions feature
│   ├── catalog/            # Product catalog feature
│   └── support/            # Support feature
├── lib/                    # Core utilities and services (replaces core/shared)
│   ├── api/                # API client and base services
│   ├── query.ts            # Query client and keys
│   ├── env.ts              # Runtime env parsing
│   ├── types/              # Shared TypeScript types
│   └── utils/              # Utility functions (cn, currency, error-display, ...)
├── providers/              # React context providers (e.g., QueryProvider)
└── styles/                # Global styles and design tokens

Design Principles

1. Feature-First Organization

Related functionality is grouped together in feature modules, making it easier to understand and maintain code.

2. Atomic Design

UI components are organized hierarchically:

• Atoms: Basic building blocks (Button, Input, etc.)
• Molecules: Combinations of atoms (SearchBar, DataTable, etc.)
• Organisms: Complex components (Layout, Header, etc.)

3. Separation of Concerns

Each feature module contains:

• components/: UI components specific to the feature
• hooks/: React hooks for state and operations
• services/: Business logic and API calls
• types/: TypeScript type definitions
• utils/: Utility functions

4. Centralized Shared Resources

Common utilities, types, and components are centralized in the lib/ and components/ directories.

Feature Module Structure

Each feature follows a consistent internal structure:

features/[feature-name]/
├── components/           # Feature-specific components
│   ├── [Component]/
│   │   ├── Component.tsx
│   │   ├── Component.test.tsx
│   │   └── index.ts
│   └── index.ts
├── hooks/               # Feature-specific hooks
│   ├── use[Feature].ts
│   └── index.ts
├── services/            # Feature business logic
│   ├── [feature].service.ts
│   └── index.ts
├── types/               # Feature-specific types
│   ├── [feature].types.ts
│   └── index.ts
├── utils/               # Feature utilities
└── index.ts             # Feature public API

Design System

The design system is built with:

Design Tokens

• CSS custom properties for consistent theming
• TypeScript constants for type safety
• Semantic color and spacing systems

Component Library

• Reusable UI components following atomic design
• Consistent styling and behavior patterns
• Accessibility-first approach

Responsive Design

• Mobile-first responsive utilities
• Consistent breakpoint system
• Container queries for component-level responsiveness

TypeScript Configuration

Enhanced TypeScript configuration with:

• Strict type checking enabled
• Path mappings for clean imports
• Enhanced error detection
• Import/export validation

Import Patterns

Recommended Import Patterns

// Feature imports
import { LoginForm, useAuth } from '@/features/auth';

// Component imports
import { Button, Input } from '@/components/ui';
import { DataTable } from '@/components/common';

// Type imports
import type { User, ApiResponse } from '@/types';

// Utility imports
import { designSystem } from '@/lib/design-system';
// Prefer feature services/hooks over direct apiClient usage in pages
import { apiClient } from '@/lib/api/client';

Path Mappings

• @/* - Root src directory
• @/components/* - Component library
• @/features/* - Feature modules
• @/lib/* - Core utilities
• @/types - Type definitions
• @/styles/* - Style files
• @shared/* - Shared package

Migration Strategy

The migration to this new architecture will be done incrementally:

1. Foundation (Current): Set up folder structure and design system
2. Core Components: Migrate base UI components
3. Feature Modules: Migrate features one by one
4. Optimization: Performance and bundle optimization
5. Cleanup: Remove old code and dependencies

Benefits

Developer Experience

• Predictable code organization
• Easy to find and modify code
• Consistent patterns across features
• Better IntelliSense and type safety

Maintainability

• Clear separation of concerns
• Reusable components and utilities
• Centralized design system
• Easier testing and debugging

Performance

• Tree-shakeable exports
• Code splitting by feature
• Optimized bundle size
• Better caching strategies

Scalability

• Easy to add new features
• Consistent architecture patterns
• Modular and composable design
• Clear boundaries between features

Pages vs Features

• Route pages under src/app/** are thin shells and do not call APIs directly.
• Data fetching and business logic live in src/features/**:
  • services/: centralized feature services built on the shared apiClient
  • hooks/: React Query hooks that wrap services and expose typed operations
  • components/: feature UI composed from shared atoms/molecules/organisms

This ensures pages remain declarative and the feature layer encapsulates logic.

Current Feature Hooks/Services

• Catalog
  • Hooks: useInternetCatalog, useSimCatalog, useVpnCatalog, useProducts*, useCalculateOrder, useSubmitOrder
  • Service: catalogService (internet/sim/vpn endpoints consolidated)
• Billing
  • Hooks: useInvoices, usePaymentMethods, usePaymentGateways, usePaymentRefresh
  • Service: BillingService
• Orders
  • Service: ordersService (list/detail/create)
• Account
  • Service: accountService (/me/address)