Skip to main content

​
System Architecture

TalentG’s architecture is designed for scalability, maintainability, and performance. This document provides a comprehensive overview of the system architecture, project structure, and component relationships.

​
High-Level Architecture

​
Project Structure

​
Monorepo Organization

TalentG/
├── apps/
│   └── isomorphic/                    # Main Next.js application
│       ├── src/
│       │   ├── app/                   # Next.js 15 App Router
│       │   │   ├── (hydrogen)/        # Main dashboard routes
│       │   │   │   ├── assessments/   # Strength Finder assessment
│       │   │   │   ├── admin/         # Admin panel routes
│       │   │   │   ├── dashboard/     # General dashboard
│       │   │   │   ├── intern-dashboard/ # Intern management
│       │   │   │   ├── learner-dashboard/ # Course learner dashboard
│       │   │   │   ├── mentor-dashboard/ # Mentor dashboard
│       │   │   │   ├── ai-resume-chat/ # AI resume features
│       │   │   │   ├── resume-builder/ # Resume creation tool
│       │   │   │   ├── career-coach/  # AI career guidance
│       │   │   │   ├── interview-questions/ # Interview prep
│       │   │   │   ├── assignments/   # Assignment system
│       │   │   │   ├── calendar/      # Event calendar
│       │   │   │   ├── courses/       # Course marketplace
│       │   │   │   ├── leaderboard/   # Gamification rankings
│       │   │   │   └── announcements/ # System announcements
│       │   │   ├── (student-layout)/  # University student portal
│       │   │   │   ├── attendance/    # Attendance tracking
│       │   │   │   ├── assignments/   # Student assignments
│       │   │   │   ├── feedback/      # Feedback system
│       │   │   │   └── resources/     # Learning resources
│       │   │   ├── api/               # API route handlers
│       │   │   │   ├── assessments/   # Assessment endpoints
│       │   │   │   ├── admin/         # Admin API routes
│       │   │   │   ├── auth/          # Authentication routes
│       │   │   │   └── storage/       # File storage routes
│       │   │   ├── auth/              # Authentication pages
│       │   │   └── shared/            # Shared layout components
│       │   ├── components/            # React components
│       │   │   ├── ui/                # RizzUI components
│       │   │   └── charts/            # Chart components
│       │   ├── lib/                   # Core utilities
│       │   │   ├── supabase/          # Supabase client configs
│       │   │   └── gemini/            # AI integration
│       │   ├── data/                  # Static data & mock data
│       │   ├── store/                 # Jotai state atoms
│       │   ├── hooks/                 # Custom React hooks
│       │   │   ├── validators/        # Zod validation schemas
│       │   │   ├── types/             # TypeScript type definitions
│       │   │   └── config/            # Application configuration
│       │   └── public/                # Static assets & media
├── packages/
│   ├── isomorphic-core/               # Shared UI components
│   │   └── src/
│   │       ├── components/            # Reusable components
│   │       └── lib/                   # Shared utilities
│   ├── config-tailwind/               # TailwindCSS configuration
│   │   └── tailwind.config.js
│   └── config-typescript/             # TypeScript configurations
│       └── tsconfig.json
├── supabase/
│   ├── migrations/                    # Database schema migrations
│   │   ├── 001_init_roles.sql         # Role-based access control
│   │   ├── 017_create_domains_tables.sql # University domains
│   │   ├── 018_create_scheduled_classes_tables.sql # Class scheduling
│   │   ├── 20250112_create_strength_finder_assessments.sql # Assessment system
│   │   └── ...                        # Additional migrations
│   └── config.toml                    # Supabase project config
├── docs/                              # Technical documentation
│   ├── project/                       # Project documentation
│   ├── developers/                    # Developer guides
│   ├── owners/                        # Owner/admin guides
│   └── api-reference/                 # API documentation
└── stagewise.json                     # Project configuration

​
Component Architecture

​
Frontend Architecture

​
Route-Based Architecture

TalentG uses Next.js 15’s App Router with a sophisticated routing structure:
  • (hydrogen): Main application routes for authenticated users
  • (student-layout): University-specific student portal
  • Public routes: Landing page, authentication, shared components

​
Component Organization

  • UI Components: RizzUI-based reusable components
  • Feature Components: Page-specific components
  • Shared Components: Cross-feature reusable components
  • Layout Components: Route-specific layouts and navigation

​
Backend Architecture

​
API Route Structure

api/
├── assessments/           # Assessment-related endpoints
│   ├── save/             # Save assessment results
│   └── [id]/             # Get assessment by ID
├── admin/                # Administrative operations
│   ├── manage-users/     # User management
│   └── analytics/        # System analytics
├── auth/                 # Authentication endpoints
│   ├── create-profile/   # User profile creation
│   └── user-avatar/      # Avatar management
├── storage/              # File storage operations
└── generate-strength-analysis/ # AI analysis endpoint

​
Database Architecture

Core Tables
  • auth.users: Supabase authentication users
  • public.profiles: Extended user profiles with roles
  • public.strength_finder_assessments: Assessment results and AI analysis
  • public.courses: Course catalog and content
  • public.enrollments: Student course enrollments
  • public.assignments: Assignment submissions and feedback
Relationship Architecture
-- User role hierarchy
auth.users (base authentication)
  ↓ extends
public.profiles (role-based profiles)
  ↓ specializes into
public.student_profiles, trainer_profiles, university_profiles

-- Assessment system
public.profiles
  ↓ creates
public.strength_finder_assessments
  ↓ contains
public.strength_finder_questions & responses

-- Learning management
public.profiles
  ↓ enrolls in
public.enrollments
  ↓ links
public.courses & assignments

​
State Management Architecture

​
Jotai-Based State Management

​
Atom Organization

store/
├── auth.ts              # Authentication state
├── assessment.ts        # Assessment progress state
├── ui.ts               # UI state (modals, notifications)
├── courses.ts          # Course-related state
└── user.ts             # User profile state

​
State Flow

  1. Server State: Initial data loaded via Server Components
  2. Client State: Jotai atoms for reactive state management
  3. Persistent State: Local storage for user preferences
  4. Real-time State: Supabase subscriptions for live updates

​
Data Flow Architecture

​
Request Flow

​
Assessment Flow

​
Security Architecture

​
Authentication Flow

​
Security Layers

  1. Network Security: HTTPS, CORS, security headers
  2. Authentication: Supabase Auth with OAuth providers
  3. Authorization: Role-based access control (RBAC)
  4. Database Security: Row Level Security (RLS) policies
  5. API Security: Input validation, rate limiting, sanitization
  6. File Security: Access controls, signed URLs, encryption

​
Performance Architecture

​
Optimization Strategies

​
Frontend Optimizations

  • Server Components: Reduced bundle size and improved TTFB
  • Image Optimization: Next.js Image component with WebP conversion
  • Code Splitting: Automatic route-based code splitting
  • Caching: Browser caching with appropriate cache headers

​
Backend Optimizations

  • Database Indexing: Optimized queries with strategic indexes
  • Connection Pooling: Efficient database connection management
  • API Caching: Response caching for frequently accessed data
  • CDN Integration: Global content delivery optimization

​
Real-time Optimizations

  • WebSocket Efficiency: Optimized real-time subscriptions
  • Debounced Updates: Reduced unnecessary real-time updates
  • Selective Subscriptions: Targeted real-time data delivery

​
Deployment Architecture

​
Vercel Deployment

​
Environment Architecture

  • Development: Local Supabase + hot reload development
  • Staging: Separate Supabase project for testing
  • Production: Optimized Supabase Cloud + Vercel Edge Network

​
Scaling Architecture

  • Horizontal Scaling: Stateless Next.js application
  • Database Scaling: Supabase’s managed PostgreSQL scaling
  • CDN Scaling: Vercel’s global edge network
  • API Scaling: Serverless function auto-scaling

​
Monitoring & Observability

​
Application Monitoring

  • Vercel Analytics: Real-time performance metrics
  • Supabase Monitoring: Database performance and usage
  • Error Tracking: Comprehensive error logging and alerting
  • User Analytics: Usage patterns and feature adoption

​
Performance Metrics

  • Core Web Vitals: Google Web Vitals tracking
  • API Response Times: Endpoint performance monitoring
  • Database Query Performance: Query optimization tracking
  • Real-time Performance: WebSocket connection monitoring

​
Future Architecture Considerations

​
Microservices Evolution

  • Service Decomposition: Breaking down monolithic features
  • API Gateway: Centralized API management and routing
  • Event-Driven Architecture: Asynchronous processing pipelines
  • Service Mesh: Advanced inter-service communication

​
Advanced Caching

  • Redis Integration: Application-level caching layer
  • Edge Caching: Global edge network caching
  • Predictive Caching: AI-driven cache warming
  • Cache Invalidation: Intelligent cache management

​
AI Architecture

  • Model Orchestration: Multiple AI models for different use cases
  • Prompt Engineering: Systematic prompt optimization
  • Response Caching: AI response caching and reuse
  • Batch Processing: Efficient bulk AI processing
This architecture provides a solid foundation for TalentG’s growth while maintaining performance, security, and developer experience.