# 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

```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 { 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`)