Assist_Design/docs/portal/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 entry points (route groups only)
│   ├── (public)/                     # Marketing + auth routes, pages import feature views
│   ├── (authenticated)/              # Signed-in portal routes, thin wrappers around features
│   ├── api/                          # App Router API routes
│   ├── favicon.ico / globals.css     # Global assets
│   └── layout.tsx                    # Root layout/providers
├── components/                       # Shared UI components (design system atoms/molecules)
│   ├── ui/
│   ├── layout/
│   └── common/
├── core/                             # App-wide configuration (env, logger, providers)
├── features/                         # Feature-specific modules composed by routes
│   ├── account/
│   ├── auth/
│   ├── billing/
│   ├── catalog/
│   ├── dashboard/
│   ├── marketing/
│   ├── orders/
│   ├── service-management/
│   ├── subscriptions/
│   └── support/
├── shared/                           # Cross-feature helpers (e.g., constants, locale data)
├── styles/                           # Global styles and design tokens
└── types/                            # Portal-specific TypeScript types

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 core/, shared/, 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 { QueryProvider } from "@/core/providers";
// Prefer feature services/hooks over direct api usage in pages
import { logger } from "@/core/config";

Path Mappings

• @/* - Root src directory
• @/components/* - Component library
• @/core/* - App-wide configuration and providers
• @/features/* - Feature modules
• @/shared/* - Shared helpers/constants
• @/styles/* - Style files
• @/types/* - Portal-specific types
• @shared/* - Shared package exports

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.

Route Layering

• (public): marketing landing and authentication flows. These routes render feature views such as marketing/PublicLandingView and auth screens while remaining server components by default.
• (authenticated): signed-in portal experience. Pages import dashboard, billing, subscriptions, etc. from the feature layer and rely on the shared route-group layout to provide navigation.
• api/: App Router API endpoints remain colocated under src/app/api and can reuse feature services for data access.

Only layout.tsx, page.tsx, and loading.tsx files live inside the route groups. All reusable UI, hooks, and services live under src/features/** to keep routing concerns thin.

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)
• Support
  • Views: SupportCasesView, NewSupportCaseView (mock data, ready for API wiring)
• Marketing
  • Views: PublicLandingView, PublicLandingLoadingView