PSA/docs/features/client-portal/client_portal_plan.md

This portal will allow your MSP clients to log in and manage their accounts, interact with support, and access necessary information. Below is a detailed plan covering required features, authentication mechanisms, and integration with your existing codebase.

Note: This document has been updated to reflect the new "client-portal" naming convention.

---

System Design for Client Portal

Objectives

• Provide MSP clients with a secure and user-friendly portal.
• Allow clients to view and manage their account information.
• Enable clients to submit and track support tickets.
• Integrate seamlessly with the existing MSP PSA system.
• Maintain strict security and data isolation between tenants.

Features

1. Authentication and Authorization

• Secure Client Login: Implement client-specific authentication to allow clients to log in securely.
• Role-Based Access Control (RBAC): Define client roles (e.g., ClientUser, ClientAdmin) and permissions.
• Multi-Factor Authentication (MFA): Optional MFA for enhanced security.
• Password Management: Allow clients to reset and change passwords securely.

2. Dashboard

• Account Overview: Display account status, active services, and recent activities.
• Notifications: Show recent notifications, announcements, or messages from the MSP.

3. Account Management

• Profile Management: Clients can view and update their company and personal contact information.
• Billing Information: View billing details, payment methods, and billing cycles.
• Service Subscriptions: View subscribed services and request changes or upgrades.

4. Support Ticketing

• Ticket Submission: Create new support tickets with the ability to attach files.
• Ticket Tracking: View the status, history, and details of existing tickets.
• Communication: Add comments to tickets and receive updates from support staff.

5. Invoices and Payments

• Invoice Access: View and download current and past invoices.
• Payment Processing: Make online payments through integrated payment gateways.
• Billing History: View payment history and upcoming billing dates.

6. Knowledge Base

• Documentation Access: Browse and search articles, FAQs, and guides.
• Search Functionality: Implement search to find relevant documentation quickly.

7. Reporting and Analytics

• Usage Reports: Access reports on service usage, time entries, and support metrics.
• Custom Reports: Allow clients to generate and export custom reports.

8. Asset Management (Optional)

• Asset Overview: View a list of assets managed by the MSP.
• Asset Details: Access detailed information about each asset, including maintenance schedules.

9. Notifications and Announcements

• System Alerts: Receive notifications about system maintenance or outages.
• Announcements: Stay informed about new services or changes.

10. Settings and Preferences

• Notification Preferences: Clients can manage how they receive notifications.
• Language and Localization: Support for multiple languages if needed.

---

System Integration

1. Codebase Structure

Based on your codebase, integration points are:

• Frontend: Under app/, create a new directory client-portal/ with its own layout.tsx and pages.
• Components: Reuse UI components from components/ and components/ui/.
• Backend: Create new API routes under app/api/client-portal/ for client-specific data handling.

2. Authentication Mechanism

Separate Authentication Flow

• Route Segregation: Authentication routes are now separated by portal type:
  • MSP Portal: /auth/msp/signin and /auth/msp/forgot-password
  • Client Portal: /auth/client-portal/signin and /auth/client-portal/forgot-password
• Shared Password Reset: /auth/password-reset/set-new-password (used by both portals)
• Client Sessions: Use next-auth sessions but with a client-specific strategy.

Implementation Details

• Portal-Specific Login Pages:
  • MSP portal uses purple theme with features list
  • Client portal uses blue theme, no self-registration
• User Type Separation: Database models include user_type field (internal for MSP, client for Client Portal)
• Authentication Middleware: Updated to handle both user types and portal-specific redirects
• Email Service: Uses SystemEmailService for authentication emails (password reset, verification)

3. Authorization

Role-Based Access Control (RBAC)

• Roles: Define roles like ClientUser, ClientAdmin.
• Permissions: Assign permissions to roles using your existing policy engine (auth/rbac.ts and policyEngine.ts).
• Policies: Write policies that enforce tenant isolation and limit clients to their data.

4. Tenant Isolation

• Middleware Checks: Ensure that all client requests include a tenant identifier.
• Data Access: Modify data access layers to filter data by tenant.

---

Detailed Implementation Plan

Step 1: Set Up Client Authentication

• Database Changes:

  • Add a userType column to the users table to distinguish between internal users and clients.
  • Ensure that client users are associated with their company (tenant).

• NextAuth Configuration:

  • Update the NextAuth options in options.ts to handle different authentication callbacks for clients.
  • Include client-specific session handling and JWT token processing.

• Authentication Pages:

  • Create client authentication pages under app/client-portal/auth/ (e.g., login.tsx, register.tsx).
  • Implement secure password reset functionality.

• Authorization Middleware:

  • Update authorizationMiddleware.ts to check the userType and restrict access accordingly.
  • Ensure that client users cannot access internal MSP routes.

Step 2: Develop the Client Portal UI

• Layout and Structure:

  • Under app/client-portal/, create the main layout (layout.tsx) and pages.
  • Use components/layout/ elements to maintain consistency.

• Dashboard Page:

  • Create a dashboard (dashboard/page.tsx) that summarizes account information.
  • Use existing components or create new ones under components/client-portal/dashboard/.

• Account Management:

  • Build pages for profile management (account/page.tsx), billing information (billing/page.tsx), and service subscriptions.
  • Use form components from components/ui/ like Input.tsx, Select.tsx, etc.

• Support Ticketing:

  • Use the ticket components from components/tickets/ and adjust them for client use.
  • Ensure that clients can only see and interact with their tickets.

• Invoices and Payments:

  • Leverage existing components from billing-dashboard/ such as Invoices.tsx.
  • Implement payment processing using secure APIs.

Step 3: Implement API Endpoints

• Client Data Endpoints:

  • Under app/api/client-portal/, create endpoints for tickets, invoices, account data, etc.
  • In each handler, enforce tenant isolation by checking the user's tenant ID.

• Data Models and Services:

  • Use existing models (models/) like Ticket, Invoice, Company.
  • Implement or extend services in lib/services/ to fetch and manipulate client data.

Step 4: Security Enhancements

• Data Validation:

  • Sanitize all inputs on the client and server side.
  • Use validation schemas where applicable.

• Audit Logging:

  • Implement logging of important actions using utils/logger.tsx.
  • Ensure compliance with data protection regulations.

• Access Control:

  • Regularly audit permissions and policies to prevent privilege escalation.

Step 5: Testing

• Unit Tests:

  • Write unit tests for new components and services.
  • Use Vitest as mentioned in your README.md.

• Integration Tests:

  • Test API endpoints, authentication flows, and data access.

• User Acceptance Testing:

  • Create test client accounts and simulate user interactions.

Step 6: Deployment

• Environment Configuration:

  • Set up environment variables for client-specific configurations.
  • Use separate domains or subdomains if necessary.

• Continuous Integration/Continuous Deployment (CI/CD):

  • Update your CI/CD pipelines to include the client portal.
  • Ensure proper build and deployment steps.

---

Codebase Integration Points

1. Reuse Existing Components

• UI Components: From components/ui/:

  • Forms (Input.tsx, Select.tsx, Button.tsx).
  • Layout components (Card.tsx, Table.tsx, Dialog.tsx).

• Business Logic Components:

  • Ticket components (components/tickets/).
  • Billing components (components/billing-dashboard/).

2. Extend Models and Services

• Models: Under models/:

  • Extend User model to differentiate client users.
  • Ensure relations between User, Company, and Tenant are correctly established.

• Services: Under lib/services/:

  • Create clientService.ts for client-specific operations.
  • Utilize taxService.ts for billing calculations if needed.

3. Authorization Middleware

• Update authorizationMiddleware.ts:
  • Implement functions to extract user roles and permissions.
  • Enforce tenant isolation by checking x-tenant-id headers.

4. Policy Engine

• Use PolicyEngine.ts:
  • Define policies for client access.
  • Enforce policies across API endpoints and UI components.

---

Security Considerations

1. Tenant Isolation

• Strict Data Access Controls:
  • Every database query should filter by tenant to prevent data leakage.
  • Use query builders that automatically include tenant filters.

2. Encryption

• Data in Transit:
  • Enforce HTTPS/TLS across the portal.
• Data at Rest:
  • Encrypt sensitive data fields in the database using methods from utils/encryption/.

3. Input Sanitization

• Prevent Injection Attacks:
  • Sanitize inputs on both client and server sides.
  • Use prepared statements and ORM features to prevent SQL injection.

4. Logging and Monitoring

• Audit Logs:
  • Log authentication attempts, data access, and significant actions.
• Monitoring:
  • Set up monitoring for unusual activities.

---

Additional Considerations

1. User Experience

• Responsive Design:
  • Ensure the portal is mobile-friendly.
• Accessibility:
  • Follow accessibility standards (e.g., WCAG) to make the portal usable for all clients.

2. Internationalization

• Localization Support:
  • If serving international clients, implement localization features.

3. Email and Notifications

• Email Service:
  • Use services/emailService.ts to send notifications.
• Notification Preferences:
  • Allow clients to opt-in or opt-out of certain notifications.

4. Documentation

• Client Documentation:
  • Provide guides on how to use the portal.
• API Documentation:
  • If exposing APIs, document them for client developers.

5. Future Expansion

• Modular Design:
  • Structure the code to allow easy addition of new features.
• Feedback Mechanism:
  • Provide a way for clients to submit feedback or request features.

---

Conclusion

By leveraging your existing codebase and adhering to best practices, you can develop a robust client portal that enhances your service offering. Remember to involve stakeholders throughout the development process to ensure that the portal meets client needs.

---

Feel free to ask if you need further details on any specific part of this plan or assistance with implementation steps!