Noumaris Internal Docs

Appearance

Completed Features ​

This page documents all completed development phases and features for the Noumaris platform.

Phase 1: Database & Authentication Foundation ​

Date Completed: October 14, 2025 Duration: 3-4 days

What Was Built ​

Database Schema:

  • 3 new tables: superadmins, resident_invitations, institution_feature_access
  • Enhanced tables: institutions, institution_admins with capacity limits
  • Foreign key relationships with cascade deletes
  • Usage tracking and capacity limits

Authentication System:

  • Fixed UUID synchronization between Keycloak and database
  • Test accounts: 1 superadmin, 2 institution admins, 3 residents
  • Keycloak realm export with predefined user IDs
  • Auto-import on container startup

Seed Data:

  • 2 test institutions with different subscription tiers
  • Feature access configuration (12 features vs 4 features)
  • Admin hierarchy setup

Testing:

  • 19 unit tests passing
  • Comprehensive test suite for all models
  • SQLite compatibility for fast testing

Test Accounts ​

All passwords: google123

Phase 2: Backend API Implementation ​

Date Completed: October 14, 2025 Duration: 5-6 days

What Was Built ​

23 REST API Endpoints:

Superadmin (8 endpoints):

  • List institutions (paginated, searchable, filterable)
  • Create/update institutions
  • Activate/suspend/expire institutions
  • Grant/revoke institution-level features
  • Create institution admins
  • System-wide analytics

Institution Admin (11 endpoints):

  • List residents (PGY filter, specialty filter)
  • Invite residents (7-day token)
  • Update/delete residents
  • Grant/revoke individual permissions
  • Bulk permission operations (all/by PGY level)
  • Usage metrics
  • Create sub-admins (senior admin only)
  • Audit log

Invitations (3 endpoints):

  • Validate invitation token (public)
  • Accept invitation (public, creates user)
  • Revoke invitation (admin only)

Security System:

  • JWT authentication with Keycloak public key validation
  • Role-based decorators: @require_superadmin, @require_institution_admin, @require_senior_admin
  • Cross-institution access protection
  • Comprehensive audit logging

Documentation:

  • 76-page API documentation
  • 75-page backend architecture guide
  • OpenAPI/Swagger auto-generated docs
  • 35-request Postman collection

Testing:

  • 26 API test cases
  • Integration workflows tested
  • In-memory SQLite for fast tests

Key Features ​

  • Pagination: All list endpoints (50 items/page default)
  • Search: Full-text search on institutions and residents
  • Filters: Status, PGY level, specialty, date range
  • Rate Limiting: 50 requests/minute for admin endpoints
  • Audit Trail: All privileged actions logged with context
  • Capacity Checks: Real-time usage validation against limits

Phase 3: Frontend Admin Dashboard ​

Date Completed: October 15, 2025 Duration: 11 days

What Was Built ​

42 React Components:

Shared Infrastructure (13 components):

  • AdminLayout, AdminSidebar - Main layout with role-aware navigation
  • DataTable - TanStack Table wrapper with sorting
  • SearchFilter - Debounced search (300ms)
  • PaginationControls - Full pagination UI
  • ConfirmDialog - Confirmation modals
  • RequireRole - Route protection HOC
  • AdminRedirect - Smart role-based redirect
  • StatusBadge - Color-coded status indicators
  • ErrorBoundary - Error catching with recovery
  • LoadingSkeleton - 7 skeleton variants (table, card, chart, list, form, page, custom)

Superadmin Dashboard (9 components):

  • SuperadminDashboard - Main dashboard with 4 analytics cards
  • InstitutionDetailPage - Detail view with 5 tabs
  • SystemAnalyticsDashboard - System-wide analytics with Recharts
  • InstitutionListTable - Data table with actions
  • CreateInstitutionModal - Creation form with validation
  • EditInstitutionModal - Edit form with capacity constraints
  • FeatureAccessMatrix - Institution-level permission matrix

Institution Admin Dashboard (12 components):

  • InstitutionAdminDashboard - Main dashboard with metrics
  • ResidentPermissionsPage - Permission management with tabs
  • UsageMetricsPage - Usage analytics with visualizations
  • AuditLogPage - Complete permission change history
  • ResidentListTable - Data table with filters
  • InviteResidentModal - Manual invitation link system
  • EditResidentModal - Resident profile editor
  • PermissionMatrix - Individual permission management
  • BulkPermissionModal - Bulk operations (all/by PGY)
  • AuditLogTable - Audit log display

API Integration:

  • Complete API client with 23 endpoints
  • React Query for data fetching, caching, mutations
  • Optimistic updates with rollback on error
  • Auto-refresh for real-time data (30-60s intervals)

Key Features Implemented ​

✅ Role-Based Access Control:

  • Automatic role detection from Keycloak JWT
  • Separate dashboards for superadmin vs institution admin
  • Route-level protection with RequireRole HOC
  • 403 Forbidden page for unauthorized access

✅ Manual Invitation System:

  • No email infrastructure required
  • Two-stage modal: Form → Success screen with invitation link
  • Copy-to-clipboard with visual feedback
  • 7-day validity, single-use tokens
  • Admin shares link manually (email, Slack, etc.)

✅ Permission Management:

  • Individual: Select resident, grant/revoke features with reason
  • Bulk: Grant/revoke to all residents or by PGY level
  • Required reason field for all changes (audit compliance)
  • Confirmation dialogs before all changes
  • Real-time cache invalidation

✅ Search, Filter, Pagination:

  • Debounced search inputs (300ms delay)
  • Multi-criteria filtering (status, PGY, specialty, date range)
  • Configurable page size (10/25/50/100 items)
  • First/Prev/Next/Last navigation
  • Total record counts displayed

✅ Real-Time Data:

  • React Query caching with 5-minute stale time
  • Auto-refresh for analytics (30-60s intervals)
  • Optimistic UI updates with rollback on error
  • Loading skeletons for better UX
  • Query invalidation after mutations

✅ Visualizations (Recharts):

  • Line charts for trend analysis
  • Pie charts for distribution
  • Bar charts for comparison
  • Dark mode styling with custom tooltips
  • Responsive containers

✅ Error Handling:

  • Error boundaries catch React errors
  • User-friendly error messages
  • Recovery options (try again, go home)
  • Toast notifications for API errors

✅ Accessibility:

  • Keyboard navigation throughout
  • ARIA labels on interactive elements
  • WCAG AA contrast ratios (4.5:1)
  • Clear focus indicators
  • Screen reader friendly

✅ Dark Mode & Responsive:

  • Full dark mode support throughout
  • Mobile-responsive design
  • Collapsible sidebar on mobile
  • Touch-friendly buttons (48px minimum)

Routes Created ​

Superadmin:

  • /admin/superadmin - Main dashboard
  • /admin/superadmin/institutions/:id - Institution detail
  • /admin/superadmin/analytics - System analytics

Institution Admin:

  • /admin/institution - Resident management
  • /admin/institution/permissions - Permission management
  • /admin/institution/usage - Usage metrics
  • /admin/institution/audit-log - Audit log

Recent Major Changes (October 2025) ​

RAG and Scraping Functionality Removed ​

Date: October 2025 Reason: Focus on core scribe value, reduce complexity, lower costs

Removed Components:

  • admin_app.py (RAG admin endpoints)
  • scraping.py (web scraping router)
  • data_processing/ directory
  • rag_engine/ and vector_store/ directories
  • Qdrant service from docker-compose
  • Database tables: scraped_documents and scraping_jobs

Benefits:

  • Simplified architecture
  • Reduced infrastructure costs
  • Faster development cycle
  • Clearer product focus

Keycloak Theme Migration (Freemarker → Keycloakify) ​

Date: October 2025 Reason: React-based, better DX, maintainable with frontend stack

Changes:

  • Moved theme from backend/keycloak/themes/ to frontend/src/keycloak-theme/
  • Created React-based theme using Keycloakify v11
  • Theme builds as JAR files for deployment
  • Custom login and registration pages

Benefits:

  • Consistent with React frontend
  • Type-safe development
  • Better developer experience
  • Easier to maintain and update

Keycloak Configuration with Terraform ​

Date: October 2025 Reason: Reproducible setup, version control, team collaboration

Changes:

  • Created terraform/keycloak/ directory
  • Terraform manages realm, roles, clients, service accounts
  • Removed manual JSON import from docker-compose
  • Created setup-local-keycloak.sh automation script

Benefits:

  • Infrastructure as Code
  • Version-controlled configuration
  • Reproducible across environments
  • Easy onboarding for new developers

Statistics ​

Code Volume ​

  • Backend: ~3,400 lines (models, APIs, tests)
  • Frontend: ~8,500 lines (42 components, API client)
  • Documentation: ~250 pages
  • Total Project: ~12,000 lines of production code

Component Breakdown ​

  • 42 React Components (13 shared, 9 superadmin, 12 institution admin, 8 utilities)
  • 23 REST API Endpoints (8 superadmin, 11 institution admin, 3 invitations, 1 permissions)
  • 19 Database Tables
  • 26 API Test Cases
  • 19 Model Test Cases

Common Workflows ​

Workflow 1: Onboard New Institution (Superadmin) ​

  1. Login as superadmin → Navigate to /admin/superadmin
  2. Click "Create Institution" button
  3. Fill form (name, email, max residents, max admins)
  4. Submit → Institution created with "Active" status
  5. Navigate to institution detail page
  6. Grant features via "Features" tab
  7. Success! Institution admins can now grant features to residents

Workflow 2: Invite and Set Up New Resident (Institution Admin) ​

  1. Login as institution admin → Navigate to /admin/institution
  2. Click "Invite Resident" button
  3. Fill invitation form (email, name, PGY level, specialty)
  4. Submit → Modal shows success screen with invitation link
  5. Copy link and share with resident manually
  6. Resident registers via Keycloak
  7. Admin grants permissions via "Permissions" page
  8. Success! Resident can now access granted features

Workflow 3: Bulk Grant Permissions (Institution Admin) ​

  1. Navigate to /admin/institution/permissions
  2. Click "Bulk Operations" button
  3. Select Action: "Grant"
  4. Select Target: "PGY-1 Residents"
  5. Select Features (multi-select)
  6. Enter Reason
  7. Review preview and confirm
  8. Success! All PGY-1 residents now have access

Last Updated: 2025-10-21

Internal documentation for Noumaris platform

Copyright © 2025 Noumaris