dbis_portal/README.md

# DBIS Portal

**Status**: 🚧 **Placeholder - Under Planning**  
**Monorepo Structure**: This project will be integrated as a submodule in the `dbis_monorepo` monorepository (when implemented) under `apps/dbis-portal`.

**Note**: `dbis_monorepo` is currently a placeholder. Integration will occur when the monorepo is implemented.

---

## Overview

DBIS Portal is a comprehensive web-based portal application that provides user interfaces for DBIS services, member bank operations, administrative functions, and public-facing information. It serves as the primary interface for users interacting with the DBIS ecosystem.

---

## Purpose

The DBIS Portal provides:

- **Member Bank Portal**: Banking operations interface for member institutions
- **Administrative Portal**: System administration and management interfaces
- **Public Portal**: Public-facing information and documentation
- **Service Management**: Service provisioning and management UI
- **Integration Hub**: Unified interface for all DBIS services

---

## Target Users

### Member Banks (Sovereign Central Banks)
- Account management
- Payment initiation and tracking
- FX trading interface
- CBDC wallet management
- Transaction history and reporting
- Compliance reporting

### System Administrators
- User and role management
- System configuration
- Monitoring dashboards
- Compliance monitoring
- Risk management interfaces
- Audit log access

### Public Users
- Service information
- Documentation access
- API documentation
- System status pages
- Registration and onboarding

---

## Architecture (Planned)

### Frontend Architecture

```
┌─────────────────────────────────────────────────────┐
│              DBIS Portal Application                 │
├─────────────────────────────────────────────────────┤
│                                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
│  │   Public     │  │   Member     │  │   Admin   │ │
│  │   Portal     │  │   Portal     │  │   Portal  │ │
│  └──────┬───────┘  └──────┬───────┘  └─────┬─────┘ │
│         │                 │                 │       │
│         └─────────────────┼─────────────────┘       │
│                           │                         │
│              ┌────────────▼────────────┐            │
│              │   Shared Components     │            │
│              │   - Layout              │            │
│              │   - Navigation          │            │
│              │   - Auth                │            │
│              │   - API Clients         │            │
│              └────────────┬────────────┘            │
│                           │                         │
│              ┌────────────▼────────────┐            │
│              │   API Integration Layer │            │
│              │   - dbis_core API       │            │
│              │   - Blockchain API      │            │
│              │   - Documentation API   │            │
│              └─────────────────────────┘            │
│                                                       │
└─────────────────────────────────────────────────────┘
```

---

## Technology Stack (Planned)

### Frontend Framework
- **Next.js 14+** (React + TypeScript)
- **App Router**: Next.js App Router for modern routing
- **Server Components**: For optimal performance
- **Server Actions**: For form handling and mutations

### UI Framework
- **TailwindCSS**: Utility-first CSS framework
- **shadcn/ui**: High-quality React components
- **Radix UI**: Accessible component primitives
- **Framer Motion**: Animations and transitions

### State Management
- **TanStack Query (React Query)**: Server state management
- **Zustand**: Client state management (if needed)
- **React Context**: Theme and global state

### Data Fetching
- **GraphQL**: For dbis_core GraphQL API
- **REST API**: For other services
- **WebSockets**: For real-time updates
- **Server Actions**: For mutations

### Authentication & Authorization
- **NextAuth.js**: Authentication framework
- **JWT**: Token-based authentication
- **RBAC**: Role-based access control
- **Integration**: With dbis_core auth system

### Form Handling
- **React Hook Form**: Form state management
- **Zod**: Schema validation
- **Server Actions**: Form submissions

---

## Project Structure (Planned)

```
dbis_portal/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (public)/           # Public routes
│   │   │   ├── page.tsx        # Landing page
│   │   │   ├── docs/           # Documentation
│   │   │   ├── api-docs/       # API documentation
│   │   │   └── status/         # Status page
│   │   ├── (member)/           # Member bank portal
│   │   │   ├── dashboard/      # Member dashboard
│   │   │   ├── accounts/       # Account management
│   │   │   ├── payments/       # Payment operations
│   │   │   ├── fx/             # FX trading
│   │   │   ├── cbdc/           # CBDC wallet
│   │   │   └── reports/        # Reports and analytics
│   │   ├── (admin)/            # Administrative portal
│   │   │   ├── dashboard/      # Admin dashboard
│   │   │   ├── users/          # User management
│   │   │   ├── monitoring/     # System monitoring
│   │   │   ├── compliance/     # Compliance monitoring
│   │   │   └── settings/       # System settings
│   │   ├── api/                # API routes
│   │   │   ├── auth/           # Authentication routes
│   │   │   └── webhook/        # Webhook handlers
│   │   ├── layout.tsx          # Root layout
│   │   └── page.tsx            # Home page
│   ├── components/             # React components
│   │   ├── ui/                 # UI components (shadcn/ui)
│   │   ├── layout/             # Layout components
│   │   ├── member/             # Member portal components
│   │   ├── admin/              # Admin portal components
│   │   ├── public/             # Public portal components
│   │   └── shared/             # Shared components
│   ├── lib/                    # Utilities and helpers
│   │   ├── api/                # API client functions
│   │   ├── auth/               # Authentication utilities
│   │   ├── utils/              # Utility functions
│   │   └── validations/        # Validation schemas (Zod)
│   ├── hooks/                  # Custom React hooks
│   ├── types/                  # TypeScript types
│   ├── styles/                 # Global styles
│   └── config/                 # Configuration
├── public/                     # Static assets
│   ├── images/
│   ├── icons/
│   └── fonts/
├── docs/                       # Documentation
│   ├── architecture/           # Architecture docs
│   ├── development/            # Development guides
│   └── deployment/             # Deployment guides
├── tests/                      # Tests
│   ├── unit/                   # Unit tests
│   ├── integration/            # Integration tests
│   └── e2e/                    # E2E tests (Playwright)
├── .env.example                # Environment variables template
├── next.config.js              # Next.js configuration
├── tailwind.config.js          # TailwindCSS configuration
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies
```

---

## Features (Planned)

### Public Portal Features
- ✅ Landing page with service information
- ✅ Documentation browser
- ✅ API documentation (interactive)
- ✅ System status dashboard
- ✅ Registration and onboarding flow
- ✅ Contact and support information

### Member Bank Portal Features
- ✅ **Dashboard**: Overview of accounts, recent transactions, alerts
- ✅ **Account Management**: 
  - Multi-asset account views
  - Account balances and history
  - Account configuration
- ✅ **Payment Operations**:
  - Payment initiation
  - Payment tracking
  - Payment history
  - Bulk payment processing
- ✅ **FX Trading**:
  - Real-time FX rates
  - FX trade execution
  - Trade history
  - Position management
- ✅ **CBDC Wallet**:
  - CBDC balance management
  - Transfer operations
  - Transaction history
  - Wallet configuration
- ✅ **Reports & Analytics**:
  - Transaction reports
  - Compliance reports
  - Financial statements
  - Custom report builder

### Administrative Portal Features
- ✅ **User Management**:
  - User creation and management
  - Role assignment
  - Permission management
  - Audit trail
- ✅ **System Monitoring**:
  - System health dashboards
  - Performance metrics
  - Error tracking
  - Service status
- ✅ **Compliance Monitoring**:
  - Compliance dashboard
  - Alert management
  - Regulatory reporting
  - Audit logs
- ✅ **Risk Management**:
  - Risk dashboard
  - Risk metrics
  - Alert configuration
  - Risk reports
- ✅ **Configuration**:
  - System settings
  - Feature flags
  - Integration configuration
  - Notification settings

---

## API Integration

### dbis_core Integration

```typescript
// API client for dbis_core
import { DBISCoreClient } from '@dbis/api-client/core';

const client = new DBISCoreClient({
  baseUrl: process.env.NEXT_PUBLIC_DBIS_CORE_API_URL,
  authToken: await getAuthToken()
});

// Fetch accounts
const accounts = await client.accounts.list();

// Initiate payment
const payment = await client.payments.create({
  from: 'account-123',
  to: 'account-456',
  amount: 1000,
  currency: 'USD'
});
```

### Blockchain Integration

```typescript
// API client for blockchain (smom-dbis-138)
import { BlockchainClient } from '@dbis/api-client/blockchain';

const blockchain = new BlockchainClient({
  rpcUrl: process.env.NEXT_PUBLIC_BLOCKCHAIN_RPC_URL,
  chainId: 138
});

// Get transaction status
const tx = await blockchain.getTransaction(txHash);

// Get account balance
const balance = await blockchain.getBalance(address);
```

### Real-Time Updates

```typescript
// WebSocket connection for real-time updates
import { useDBISWebSocket } from '@/hooks/use-dbis-websocket';

function PaymentTracker({ paymentId }) {
  const { payment, status } = useDBISWebSocket(`payments/${paymentId}`);
  
  return <div>Status: {status}</div>;
}
```

---

## Authentication & Authorization

### Authentication Flow

1. **Login**: User authenticates via NextAuth.js
2. **Token Management**: JWT tokens stored securely
3. **Session Management**: Server-side session handling
4. **Multi-Factor Authentication**: Support for MFA

### Authorization

- **Role-Based Access Control (RBAC)**:
  - Public users
  - Member bank users
  - System administrators
  - Super administrators

- **Permission-Based Access**:
  - Fine-grained permissions
  - Feature-level access control
  - API-level permissions

### Integration

```typescript
// Authentication middleware
import { withAuth } from '@/lib/auth/middleware';

export const middleware = withAuth({
  publicRoutes: ['/', '/docs', '/status'],
  memberRoutes: ['/member'],
  adminRoutes: ['/admin']
});
```

---

## Deployment (Planned)

### Infrastructure

- **Hosting**: Next.js can deploy to:
  - Vercel (recommended for Next.js)
  - Azure Static Web Apps
  - Kubernetes (AKS)
  - Docker containers

### Environment Variables

```env
# API Endpoints
NEXT_PUBLIC_DBIS_CORE_API_URL=https://api.dbis.local
NEXT_PUBLIC_BLOCKCHAIN_RPC_URL=https://rpc.dbis.local
NEXT_PUBLIC_DOCS_API_URL=https://docs.dbis.local

# Authentication
NEXTAUTH_URL=https://portal.dbis.local
NEXTAUTH_SECRET=your-secret-key
NEXT_PUBLIC_AUTH_PROVIDER=dbis-core

# Feature Flags
NEXT_PUBLIC_ENABLE_FX_TRADING=true
NEXT_PUBLIC_ENABLE_CBDC_WALLET=true

# Analytics (optional)
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
```

### Deployment Methods

**Option 1: Vercel (Recommended)**
```bash
vercel deploy
```

**Option 2: Docker**
```bash
docker build -t dbis-portal .
docker run -p 3000:3000 dbis-portal
```

**Option 3: Kubernetes**
```bash
kubectl apply -f k8s/
```

---

## Development (Planned)

### Prerequisites

- Node.js >= 18.0.0
- pnpm >= 8.0.0 (recommended) or npm/yarn
- Access to dbis_core API (for development)

### Setup

```bash
# Clone repository (or as submodule)
git clone <repository-url>
cd dbis_portal

# Or as submodule in dbis_monorepo
cd dbis_monorepo/apps/dbis-portal

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your configuration

# Run development server
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start
```

### Development Commands

```bash
# Development server
pnpm dev

# Build
pnpm build

# Type checking
pnpm type-check

# Linting
pnpm lint

# Formatting
pnpm format

# Testing
pnpm test              # Unit tests
pnpm test:e2e          # E2E tests
pnpm test:coverage     # Coverage report
```

---

## Testing Strategy (Planned)

### Unit Tests
- Component tests (React Testing Library)
- Utility function tests (Jest/Vitest)
- Hook tests

### Integration Tests
- API integration tests
- Authentication flow tests
- Payment flow tests

### E2E Tests
- User workflows (Playwright)
- Critical user journeys
- Cross-browser testing

### Test Structure

```
tests/
├── unit/
│   ├── components/
│   ├── lib/
│   └── hooks/
├── integration/
│   ├── api/
│   └── flows/
└── e2e/
    ├── member-portal.spec.ts
    ├── admin-portal.spec.ts
    └── public-portal.spec.ts
```

---

## Performance Optimization (Planned)

### Next.js Optimizations
- Server Components for reduced client bundle
- Image optimization
- Code splitting
- Route prefetching
- Static generation where possible

### API Optimizations
- Request caching (TanStack Query)
- Optimistic updates
- Batch requests
- Debounced search

### Asset Optimization
- Image optimization
- Font optimization
- CSS optimization
- Bundle analysis

---

## Security (Planned)

### Frontend Security
- XSS protection (React default)
- CSRF protection
- Content Security Policy (CSP)
- Secure token storage
- Input sanitization

### API Security
- Secure API communication (HTTPS)
- Token-based authentication
- Rate limiting
- Request validation

### Data Privacy
- GDPR compliance
- Data encryption
- Secure session management
- Privacy policy integration

---

## Monorepo Integration

### As Submodule in dbis_monorepo

This project will be integrated as a git submodule:

```bash
# In dbis_monorepo root
git submodule add <repository-url> apps/dbis-portal
cd apps/dbis-portal
git submodule update --init --recursive
```

### Shared Packages

When part of the monorepo, this project will use:

- **@dbis/shared**: Shared utilities and types
- **@dbis/api-client**: API client libraries
- **@dbis/schemas**: Shared schemas and validation
- **@dbis/auth**: Authentication utilities

### Example Usage

```typescript
// Using shared packages
import { DBISConfig } from '@dbis/shared';
import { DBISCoreClient } from '@dbis/api-client/core';
import { TransactionSchema } from '@dbis/schemas';
import { authenticate } from '@dbis/auth';
```

---

## Roadmap

### Phase 1: Foundation (Weeks 1-4)
- [ ] Next.js project setup
- [ ] UI component library setup (shadcn/ui)
- [ ] Authentication integration
- [ ] Basic layout and navigation
- [ ] API client setup

### Phase 2: Public Portal (Weeks 5-8)
- [ ] Landing page
- [ ] Documentation browser
- [ ] API documentation
- [ ] Status page
- [ ] Public-facing features

### Phase 3: Member Portal (Weeks 9-14)
- [ ] Dashboard
- [ ] Account management
- [ ] Payment operations
- [ ] FX trading interface
- [ ] CBDC wallet
- [ ] Reports and analytics

### Phase 4: Admin Portal (Weeks 15-18)
- [ ] User management
- [ ] System monitoring
- [ ] Compliance monitoring
- [ ] Risk management
- [ ] System configuration

### Phase 5: Integration & Polish (Weeks 19-20)
- [ ] Integration testing
- [ ] Performance optimization
- [ ] Security hardening
- [ ] Documentation
- [ ] Production deployment

---

## Related Projects

- **[dbis_core](../dbis_core/)** - Core banking API (primary integration)
- **[smom-dbis-138](../smom-dbis-138/)** - Blockchain API (for blockchain features)
- **[dbis_docs](../dbis_docs/)** - Documentation API (for docs browser)
- **[dbis_monorepo](../dbis_monorepo/)** - Monorepo parent (this project as submodule)
- **[dbis_dc_tools](../dbis_dc_tools/)** - Infrastructure tools (for deployment)

---

## Contributing

When contributing:

1. Follow Next.js best practices
2. Use shared components from @dbis/shared
3. Write tests for new features
4. Update documentation
5. Ensure accessibility (WCAG 2.1 AA)

---

## License

[To be determined - will align with DBIS licensing]

---

## Status

**Current Status**: 🚧 Placeholder  
**Next Steps**: 
- Finalize requirements and user stories
- Set up Next.js project structure
- Design UI/UX mockups
- Begin Phase 1 development
- Integrate into dbis_monorepo

---

**Last Updated**: 2025-01-27  
**Monorepo Integration**: Pending - Will be submodule in `dbis_monorepo/apps/dbis-portal`