212 lines
7.3 KiB
Markdown
212 lines
7.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 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`
|