Authentication Documentation

This directory contains comprehensive documentation for the Kulcare platform's authentication system.

Table of ContentsCopy Anchor Link

Core DocumentationCopy Anchor Link

1. Authentication Architecture

   • Complete technical overview of the auth system
   • State management with Zustand
   • Token management and security
   • API integration details
   • Implementation guide with code examples

2. Authentication Flow

   • User journey from login to accessing protected resources
   • Cross-app authentication sharing
   • Standalone vs federated mode handling
   • Clinic selection process

3. Logout Implementation 🆕

   • Comprehensive logout functionality
   • Complete data clearing from browser storage
   • Cross-tab synchronization
   • Event-based architecture
   • 401 unauthorized handling

4. Change Password 🆕

   • Complete change password implementation
   • Clean architecture with separation of concerns
   • Real-time password validation
   • Custom hook pattern for business logic
   • Security best practices

Implementation GuidesCopy Anchor Link

5. Login Implementation Plan

   • Step-by-step plan for implementing login
   • Component structure
   • API integration approach

6. Login Implementation Summary

   • Summary of implemented login features
   • Key decisions and patterns used

Testing DocumentationCopy Anchor Link

7. Testing Authentication

   • Test strategies for auth flows
   • Unit and integration test examples
   • Mock data setup

8. Testing Login

   • Specific login testing scenarios
   • E2E test examples

Technical ReferencesCopy Anchor Link

9. CORS Solution

   • Cross-origin resource sharing configuration
   • API client setup for CORS

10. Login Sample

    • Sample login implementation code
    • Reference for developers

Roles and PermissionsCopy Anchor Link

11. Roles and Permissions (RBAC)
    • The model: roles, permission keys, tenant rows, and per-user overrides
    • The resolution order and the GET /identity/my/permissions endpoint
    • How to add a key, change a default, and gate an action
    • The grant ceiling, invites, the tests, and the deploy step
    • Pundit rules: Authorization (Pundit policies)

Quick StartCopy Anchor Link

For developers implementing authentication features:

1. Start with Authentication Architecture for overall understanding
2. Review Authentication Flow for user journey
3. Check Logout Implementation for proper session termination
4. See Change Password for password management implementation
5. Use Testing Authentication for test implementation

Key FeaturesCopy Anchor Link

• 🔐 JWT-based authentication with automatic token refresh
• 🏥 Multi-clinic support for healthcare providers
• 👥 Role-based access control (RBAC)
• 💾 Persistent sessions across page refreshes
• 🔄 Cross-tab synchronization for consistent state
• 🚪 Comprehensive logout with complete data clearing
• 🛡️ Security-first design with proper token handling

Security ConsiderationsCopy Anchor Link

• Always use HTTPS in production
• Tokens are stored securely in localStorage
• Automatic logout on 401 responses
• Complete session termination on logout
• No sensitive data persisted after logout

Integration with Micro-FrontendsCopy Anchor Link

The authentication system is designed to work seamlessly across all micro-frontends:

• Shell App: Handles login, logout, and clinic selection
• CMS App: Protected routes require authentication
• Growth App: Shares authentication state with other apps
• Future Apps: Will integrate the same auth patterns

All apps use the @kulcare/auth package for consistent authentication handling.