Noumaris Internal Docs

Appearance

In Progress Features ​

Features currently under active development.

Terraform Keycloak Configuration ​

Status: 🚧 In Progress Started: 2025-10-15 Target: 2025-10-22 Owner: Development Team

Overview ​

Migrating Keycloak realm configuration from manual JSON imports to Terraform-managed infrastructure for reproducible, version-controlled setup across all environments.

What We're Building ​

  • Terraform Module: terraform/keycloak/ with realm, roles, clients configuration
  • Automation Script: scripts/setup-local-keycloak.sh for local dev setup
  • Documentation: Complete guide for local and production deployment

Implementation Status ​

✅ Completed:

  • Research Terraform Keycloak provider (mrparkers/keycloak v4.3)
  • Create terraform/keycloak/ structure
  • Define realm configuration
  • Define roles (superadmin, institution_admin, resident, user)
  • Define frontend client (fastapi-frontend)
  • Define service account client (noumaris-admin-service)

🚧 In Progress:

  • Write and test setup-local-keycloak.sh script
  • Test on fresh Docker environment
  • Update CLAUDE.md documentation

📋 Remaining:

  • Production deployment configuration
  • CI/CD integration for Keycloak changes

Decision Points During Development ​

1. Terraform Provider Choice ​

Challenge: Which Terraform provider for Keycloak? Options:

  • mrparkers/keycloak (community, actively maintained)
  • keycloak/keycloak (official but less mature) Decision: Use mrparkers/keycloak v4.3 Rationale:
  • More mature and feature-complete
  • Better documentation
  • Active community support
  • Used by many production deployments

2. State Management ​

Challenge: Where to store Terraform state? Options:

  • Local state file (.tfstate)
  • Remote state (Terraform Cloud, GCS, S3) Decision: Local state for now, remote state for production Rationale:
  • Local development doesn't need remote state
  • Production will use Google Cloud Storage backend
  • Easier onboarding for developers

Challenges & Solutions ​

Challenge: Keycloak Docker container takes time to start Solution: Added health check loop in setup script with 30s timeout

Challenge: Terraform provider auth for local Keycloak Solution: Use admin/admin credentials for local, env vars for production

Testing Checklist ​

  • [x] Terraform plan succeeds
  • [x] Terraform apply creates realm
  • [x] All roles created correctly
  • [ ] Frontend client authentication works
  • [ ] Backend service account works
  • [ ] Fresh Docker setup succeeds
  • [ ] Documentation accurate

Next Steps ​

  1. Complete setup script testing
  2. Document in CLAUDE.md
  3. Create production configuration
  4. Add to CI/CD pipeline

Permissions Context (Frontend) ​

Status: 🚧 In Progress Started: 2025-10-16 Target: 2025-10-23 Owner: Development Team

Overview ​

Create React context for managing user permissions throughout the frontend application, enabling permission-based UI rendering and feature access control.

What We're Building ​

  • PermissionsContext: React context with permissions state
  • usePermissions Hook: Custom hook for accessing permissions
  • Permission Guards: Components like <RequirePermission feature="..." />
  • Integration: Connect to backend permission API

Implementation Status ​

📋 Planned:

  • Create PermissionsContext.jsx
  • Implement usePermissions hook
  • Create RequirePermission component
  • Add permission checks to existing components
  • Integrate with backend /permissions endpoint
  • Add loading and error states

Technical Design ​

javascript
// Example usage
const { hasPermission, loading } = usePermissions();

if (loading) return <Skeleton />;

if (hasPermission('live_transcription')) {
  return <TranscriptionButton />;
}

return <UpgradePrompt feature="live_transcription" />;

Next Steps ​

  1. Design context structure
  2. Implement basic context and hook
  3. Add to App.jsx provider tree
  4. Integrate with backend API
  5. Add to existing components

Frontend TypeScript Migration ​

Status: 🚧 In Progress Started: 2025-10-20 Target: 2025-11-05 Owner: Frontend Guild

Overview ​

Gradually converting React modules from JavaScript to TypeScript to unlock type-safe API integration, reduce runtime bugs, and standardize shared admin primitives.

What We're Building ​

  • Typed Shared Components: Convert features/admin/shared/components/* to .tsx with discriminated unions where needed.
  • Typed API Clients: Move REST helpers to frontend/src/lib/api/*.ts and generate types/*.ts models.
  • Query Layer: Centralize keys in lib/queryClient.ts with typed helpers for invalidation.
  • Developer Notes: Track decisions and blockers in frontend/ts-migration-notes.md.

Implementation Status ​

✅ Completed:

  • ConfirmDialog, DataTable, EmptyState, LoadingSkeleton, and StatusBadge rewritten in TypeScript.
  • SuperadminInstitutionContext.tsx typed with React Query integration.
  • API clients for admin and invitations now export typed responses.
  • queryClient.ts introduces typed query keys and retry behaviour.

🚧 In Progress:

  • Convert admin layout shell (AdminLayout.tsx) to strict typing and migrate sidebar props.
  • Migrate resident feature components with evolving data models.
  • Adopt TypeScript-aware ESLint rules once coverage exceeds 70%.

📋 Remaining:

  • Update analytics dashboards (SystemAnalyticsDashboard.jsx) to TypeScript once charting types are ready.
  • Replace legacy lib/api.js helpers with typed wrappers or remove after migration.
  • Wire TypeScript builds into CI (npm run typecheck) as a required status check.

Risks & Mitigations ​

  • Third-party typings (e.g., older chart libraries) still rely on ambient any. Document workarounds in ts-migration-notes.md.
  • Mixed modules may break imports from .js → .ts. Track rename tasks per folder to avoid circular dependencies.

Documentation System (VitePress) ​

Status: 🚧 In Progress (Current Task) Started: 2025-10-21 Target: 2025-10-23 Owner: Development Team

Overview ​

Building a comprehensive documentation system using VitePress to serve AI agents (Claude) and human developers with ~25 core documentation files organized in a layered pyramid structure.

Implementation Status ​

✅ Completed:

  • Phase 1: VitePress setup and directory structure
  • Phase 2: Core documentation files (indexes, onboarding)

🚧 In Progress:

  • Phase 3: Migrating existing documentation

📋 Remaining:

  • Phase 4: Create Architecture Decision Records (ADRs)
  • Phase 5: Detailed documentation expansion
  • Phase 6: Reference & compliance docs
  • Phase 7: Update CLAUDE.md

Benefits ​

  • Token Efficiency: ~2-3k tokens per AI query (vs 15k+ with scattered docs)
  • Better Onboarding: New developers productive in <4 hours
  • Decision Transparency: All architectural decisions documented
  • Knowledge Retention: Zero tribal knowledge

Next Steps ​

  1. Complete migration of existing docs
  2. Create 7+ ADRs
  3. Expand architecture documentation
  4. Add reference materials
  5. Update CLAUDE.md

Last Updated: 2025-10-21

Internal documentation for Noumaris platform

Copyright © 2025 Noumaris