a95ec60859
- Updated address retrieval in user service to replace billing info with a dedicated address method. - Adjusted API endpoints to use `PATCH /api/me/address` for address updates instead of billing updates. - Enhanced documentation to reflect changes in address management processes and API usage. - Removed deprecated types and services related to billing address handling, streamlining the codebase.
194 lines
6.3 KiB
Markdown
194 lines
6.3 KiB
Markdown
# 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`)
|