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 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

```typescript
// 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`