# Portal Architecture This document outlines the feature-driven architecture implemented for the customer portal. --- ## Quick Reference | Aspect | Location | | --------------------- | ----------------------------------------------------------- | | **Feature modules** | `apps/portal/src/features/` | | **Shared components** | `apps/portal/src/components/` (atomic design) | | **API client** | `apps/portal/src/core/api/index.ts` | | **Query keys** | `apps/portal/src/core/api/index.ts` → `queryKeys` | | **Domain types** | `import type { X } from "@customer-portal/domain/"` | **Key patterns**: - Pages are thin wrappers → import views from features - Features contain: `api/`, `hooks/`, `stores/`, `components/`, `views/` - Use React Query hooks from features (e.g., `useInvoices` from `@/features/billing`) --- ## 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/ │ ├── address/ # Address management and Japan Post lookup │ ├── auth/ │ ├── billing/ │ ├── checkout/ │ ├── dashboard/ │ ├── get-started/ # Unified signup and eligibility flow │ ├── 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 ``` ## 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. ## Feature Module Inventory | Feature | API Service | Key Hooks | Purpose | | --------------- | --------------------------------------------- | ------------------------------------------------------- | ------------------------------ | | `account` | `accountService` | `useProfileEdit`, `useAddressEdit` | Profile and address management | | `address` | `addressService` | `useAddressLookup` | Japan Post address lookup | | `auth` | (via store) | `useAuthStore`, `useAuthSession` | Authentication state | | `billing` | `billingService` | `useInvoices`, `usePaymentMethods`, `usePaymentRefresh` | Invoices and payments | | `checkout` | `checkoutService` | `useCheckoutStore` | Checkout flow | | `dashboard` | `getMeStatus` | `useMeStatus` | Dashboard data | | `get-started` | `getStartedService` | `useGetStartedFlow` | Unified signup flow | | `landing-page` | — | — | Marketing landing page | | `marketing` | — | — | Marketing components | | `notifications` | `notificationService` | `useNotifications` | User notifications | | `orders` | `ordersService` | `useOrdersList`, `useOrderDetail` | Order management | | `realtime` | — | `useRealtimeEvents` | SSE/WebSocket events | | `services` | `servicesService` | `useInternetCatalog`, `useSimCatalog`, `useVpnCatalog` | Product catalog | | `subscriptions` | `simActionsService`, `internetActionsService` | `useSubscriptions` | Active service management | | `support` | `supportService` | `useCases`, `useCreateCase` | Support tickets | | `verification` | `verificationService` | `useResidenceCardVerification` | ID verification | ## 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