87fa789fce
- Introduced `accountService` for managing user profiles, including fetching and updating profile and address information. - Created `auth.store` to handle client-side authentication state, including login, signup, and session management. - Added centralized exports for authentication services in `auth/api/index.ts`. - Implemented API services for billing and checkout functionalities, enhancing the overall service architecture. - Established a new structure for service APIs, promoting better organization and maintainability across the portal features.
227 lines
9.1 KiB
Markdown
227 lines
9.1 KiB
Markdown
# 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
|