System Architecture
Understanding the design, patterns, and technology stack behind OMOBL SSO
Technology Stack
- Next.js 15+ - React framework with App Router
- TypeScript 5+ - Type-safe development
- Tailwind CSS - Utility-first styling
- shadcn/ui - Accessible component library
- Recharts - Data visualization
- Zustand - State management
- PostgreSQL 16+ - Primary database
- Prisma 6.x - Type-safe ORM
- Clerk - Authentication provider
- Next.js API Routes - RESTful endpoints
- Zod - Schema validation
- AES-256-GCM - Secret encryption
Architecture Layers
Presentation Layer
React Server Components and Client Components for the UI
app/dashboard/- User dashboardsapp/admin/- Admin interfacescomponents/- Reusable UI components
API Layer
RESTful API routes and webhook handlers
app/api/users/- User management endpointsapp/api/groups/- Group management endpointsapp/api/webhooks/- Clerk webhook handlers
Service Layer
Business logic and domain services
user.service.ts- User business logicgroup.service.ts- Group hierarchy managementanalytics.service.ts- Metrics aggregation
Repository Layer
Data access and database operations
user.repository.ts- User data accessgroup.repository.ts- Group data accessbase.repository.ts- Base CRUD operations
Design Patterns
Abstracts data access logic from business logic. Each entity (User, Group, Application) has its own repository for database operations.
Encapsulates business logic and orchestrates operations across multiple repositories. Services handle complex workflows and validation.
Creates instances of services and repositories with proper dependency injection. Ensures consistent initialization across the application.
React Context providers for theme, authentication, and global state management. Enables data sharing across component trees.
Request Flow
User Request
↓
Middleware (auth check)
↓
API Route Handler
↓
Service Layer (business logic)
↓
Repository Layer (data access)
↓
Prisma ORM
↓
PostgreSQL Database
↓
Response (JSON)Each request flows through authentication middleware, then to the appropriate API handler, which delegates to services for business logic and repositories for data access.
Feature Architecture
Four-tier role system with granular permissions:
Master Admin
Full system access, VIEW AS, impersonation
Group Admin
Manage groups, members, and group apps
Member
Access group apps and view member directory
Application User
User-specific app visibility control
See Authorization for detailed permission matrix.
Unlimited group nesting with permission inheritance:
Organization (Root)
├── Engineering
│ ├── Frontend Team
│ └── Backend Team
├── Sales
│ ├── North America
│ └── Europe
└── MarketingEach group can have its own theme, admins, members, and application assignments.
Security Architecture
Authentication
- • Clerk-managed user authentication
- • JWT session tokens
- • Webhook-based data synchronization
Encryption
- • AES-256-GCM for OAuth secrets
- • Bcrypt for invitation tokens
- • TLS/SSL for data in transit
Input Validation
- • Zod schema validation
- • Prisma parameterized queries
- • CSRF protection built-in
Audit Logging
- • All CRUD operations logged
- • Actor tracking and timestamps
- • Change snapshots (before/after)
- Database Schema - Explore the complete data model
- Authentication Flow - Understand Clerk integration
- Authorization System - Learn about RBAC implementation
- Security Overview - Security features and best practices