Assist_Design/docs/development/portal/architecture.md

# Portal Architecture

This document outlines the 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
│   ├── account/                      # Authenticated 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/                        # Basic building blocks (Button, Input, Badge, etc.)
│   ├── molecules/                    # Combinations of atoms (DataTable, FormField, etc.)
│   ├── organisms/                    # Complex UI sections (AppShell, SiteFooter, etc.)
│   └── templates/                    # Page-level layouts (AuthLayout, PageLayout, etc.)
├── core/                             # App-wide infrastructure
│   ├── api/                          # HTTP client, query keys, error handling
│   ├── logger/                       # Application logging
│   └── providers/                    # React context providers (QueryProvider)
├── features/                         # Feature-specific modules composed by routes
│   ├── account/
│   ├── auth/
│   ├── billing/
│   ├── checkout/
│   ├── dashboard/
│   ├── landing-page/
│   ├── marketing/
│   ├── notifications/
│   ├── orders/
│   ├── realtime/
│   ├── services/                     # Service browsing and ordering (pre-purchase)
│   ├── subscriptions/                # Subscription management
│   ├── support/
│   └── verification/
├── shared/                           # Cross-feature helpers
│   ├── api/                          # Shared API services (currency, etc.)
│   ├── constants/                    # Data constants (countries, prefectures)
│   ├── hooks/                        # Generic React hooks
│   └── utils/                        # General utilities (cn, date, error-handling)
├── styles/                           # Global styles and design tokens
├── config/                           # Environment configuration
└── lib/                              # Legacy (deprecated, re-exports from core/shared)
```

## 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 follow atomic design principles:

- **Atoms**: Basic building blocks (Button, Input, Badge, Spinner, etc.)
- **Molecules**: Combinations of atoms (DataTable, FormField, AlertBanner, etc.)
- **Organisms**: Complex UI sections (AppShell, SiteFooter, AgentforceWidget)
- **Templates**: Page-level layouts (AuthLayout, PageLayout, PublicShell)

### 3. Separation of Concerns

Each feature module contains:

- `api/`: Data fetching and API calls
- `stores/`: State management (Zustand stores)
- `components/`: UI components specific to the feature
- `hooks/`: React hooks for state and operations
- `views/`: Page-level view components
- `utils/`: Utility functions
- `index.ts`: Feature public API (barrel exports)

### 4. Centralized Shared Resources

- `core/`: App-wide infrastructure (API client, logging, providers)
- `shared/`: Cross-feature utilities, hooks, and constants
- `components/`: Reusable UI components following atomic design

## Feature Module Structure

Each feature follows a consistent internal structure:

```
features/[feature-name]/
├── api/                 # Data fetching layer
│   ├── [feature].api.ts
│   └── index.ts
├── stores/              # State management (if needed)
│   ├── [feature].store.ts
│   └── index.ts
├── components/          # Feature-specific components
│   ├── [Component].tsx
│   └── index.ts
├── hooks/               # Feature-specific hooks
│   ├── use[Feature].ts
│   └── index.ts
├── views/               # Page-level views
│   └── [Feature]View.tsx
├── utils/               # Feature utilities
└── index.ts             # Feature public API
```

## Core vs Shared

### Core (`@/core/`)

App-wide infrastructure that features depend on:

- **api/**: HTTP client, query keys, response helpers, error handling
- **logger/**: Application logging utilities
- **providers/**: React context providers (QueryProvider)

### Shared (`@/shared/`)

Cross-feature utilities that aren't infrastructure:

- **api/**: Shared API services (currency)
- **constants/**: Data constants (countries, prefectures)
- **hooks/**: Generic React hooks (useLocalStorage, useDebounce, useMediaQuery)
- **utils/**: General utilities (cn, date formatting, error handling)

## Import Patterns

### Recommended Import Patterns

```typescript
// Feature imports (prefer barrel exports)
import { LoginForm, useAuthStore } from "@/features/auth";
import { billingService, useInvoices } from "@/features/billing";

// Component imports (atomic design)
import { Button, Badge, Spinner } from "@/components/atoms";
import { DataTable, FormField } from "@/components/molecules";
import { AppShell } from "@/components/organisms";

// Core infrastructure
import { apiClient, queryKeys } from "@/core/api";
import { logger } from "@/core/logger";
import { QueryProvider } from "@/core/providers";

// Shared utilities
import { cn, formatIsoDate } from "@/shared/utils";
import { useDebounce, useMediaQuery } from "@/shared/hooks";
import { countries, japanPrefectures } from "@/shared/constants";

// Domain types (from shared package)
import type { Invoice } from "@customer-portal/domain/billing";
```

### Path Mappings

- `@/*` - Root src directory
- `@/components/*` - Component library (atomic design)
- `@/core/*` - App-wide infrastructure
- `@/features/*` - Feature modules
- `@/shared/*` - Cross-feature utilities
- `@/styles/*` - Style files
- `@/config/*` - Environment configuration

## 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/**`:
  - `api/`: Feature API services built on the shared `apiClient`
  - `hooks/`: React Query hooks that wrap API services
  - `stores/`: Zustand stores for complex state management
  - `components/`: Feature UI composed from shared atoms/molecules/organisms
  - `views/`: Page-level view components

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

### Route Layering

- `(public)`: Marketing landing and authentication flows
- `account/`: Authenticated portal experience (dashboard, billing, subscriptions, etc.)
- `api/`: App Router API endpoints

Only `layout.tsx`, `page.tsx`, and `loading.tsx` files live inside the route groups.

## Current Feature API/Hooks

| Feature       | API Service                                   | Hooks                                                   |
| ------------- | --------------------------------------------- | ------------------------------------------------------- |
| auth          | (via store)                                   | `useAuthStore`, `useAuthSession`                        |
| services      | `servicesService`                             | `useInternetCatalog`, `useSimCatalog`, `useVpnCatalog`  |
| billing       | `billingService`                              | `useInvoices`, `usePaymentMethods`, `usePaymentRefresh` |
| orders        | `ordersService`                               | `useOrdersList`, `useOrderDetail`                       |
| account       | `accountService`                              | `useProfileEdit`, `useAddressEdit`                      |
| subscriptions | `simActionsService`, `internetActionsService` | `useSubscriptions`                                      |
| notifications | `notificationService`                         | `useNotifications`                                      |
| verification  | `verificationService`                         | `useResidenceCardVerification`                          |
| checkout      | `checkoutService`                             | `useCheckoutStore`                                      |
| dashboard     | `getMeStatus`                                 | `useMeStatus`                                           |

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