Platform Guide

Architecture Overview

Persona Recruit AI is a Multi-Tenant SaaS Application built on a modern serverless architecture using Firebase and Next.js.

Core Principles

• Multi-Tenancy: Each company has completely isolated data
• Event-Driven Architecture: Firebase Functions respond to database changes
• AI-First Design: Golden JSON schemas ensure strict AI contracts
• Human-in-the-Loop: AI assists, humans decide

Technology Stack

Frontend Stack

• Next.js 15: React framework with App Router
• React 18: UI library with Suspense and concurrent features
• TypeScript: Type-safe development
• Tailwind CSS: Utility-first styling
• Shadcn/UI: Accessible component library

Backend Stack

• Firebase: Backend-as-a-Service platform
• Firestore: NoSQL document database
• Cloud Functions: Serverless compute
• Cloud Storage: File storage
• Firebase Auth: Authentication service

AI & ML

• Google Genkit: AI orchestration framework
• Gemini AI: Large language models
• Vector Embeddings: Semantic search
• ElevenLabs: Voice synthesis (planned)

Development Environment

Local Setup

# Clone repository git clone https://github.com/your-org/persona-recruit-ai.git cd persona-recruit-ai # Install dependencies npm install # Set up environment variables cp .env.example .env.local # Edit .env.local with your Firebase config # Start development server npm run dev

Required Tools

• Node.js v18+ LTS
• npm v9+
• Firebase CLI v12+
• Git v2.30+
• VS Code (recommended)

Database Schema

Core Collections

users - User accounts and profiles

interface User {
  id: string;
  email: string;
  role: 'candidate' | 'recruiter' | 'interviewer' | 'hr_admin' | 'platform_admin';
  companyId?: string; // null for candidates and platform_admin
  profile: {
    firstName: string;
    lastName: string;
    avatar?: string;
    timezone: string;
  };
  createdAt: Timestamp;
  updatedAt: Timestamp;
}

jobs - Job postings

interface Job {
  id: string;
  companyId: string;
  title: string;
  department: string;
  location: string;
  type: 'full-time' | 'part-time' | 'contract' | 'internship';
  status: 'draft' | 'open' | 'on-hold' | 'closed' | 'filled';
  description: string;
  requirements: {
    required: string[];
    preferred: string[];
    experience: 'entry' | 'mid' | 'senior' | 'executive';
  };
  aiConfig: {
    autoRejectThreshold: number;
    matchingWeights: MatchingWeights;
  };
  createdAt: Timestamp;
}

applications - Job applications

interface Application {
  id: string; // Custom format: APP-2025-0001
  jobId: string;
  candidateId: string;
  companyId: string;
  status: ApplicationStatus;
  stage: ApplicationStage;
  appliedAt: Timestamp;
  aiAnalysis?: {
    matchScore: number;
    recommendation: string;
    strengths: string[];
    concerns: string[];
    summary: string;
  };
}

AI & Genkit Integration

Available AI Agents

• Resume Parser: Extracts structured data from resumes
• Job Matcher: Calculates candidate-job compatibility scores
• Candidate Summarizer: Generates recruiter-friendly summaries
• Interview Assistant: Creates relevant interview questions
• Email Composer: AI-assisted email writing

Model Configuration

export const AI_CONFIG = {
  models: {
    gemini20Flash: {
      model: 'gemini-2.0-flash-exp',
      temperature: 0.3,
      maxOutputTokens: 4000,
      topP: 0.8,
      topK: 40
    },
    gemini15Pro: {
      model: 'gemini-1.5-pro',
      temperature: 0.5,
      maxOutputTokens: 8000,
      topP: 0.9,
      topK: 50
    }
  }
};

Deployment Guide

Firebase App Hosting

# Build for production npm run build # Deploy to Firebase firebase deploy # Deploy specific services firebase deploy --only hosting firebase deploy --only functions firebase deploy --only firestore:rules

Environment Configuration

• Development: Local development with emulators
• Production: Firebase App Hosting deployment
• Environment Variables: Firebase Secret Manager
• CI/CD: GitHub Actions pipeline

Security Considerations

Authentication & Authorization

• Firebase Auth: Email/password and OAuth providers
• Role-Based Access Control: Fine-grained permissions
• Multi-Tenant Security: Company-level data isolation
• API Protection: Token-based authentication

Data Privacy

• GDPR Compliance: Data subject rights implementation
• Data Encryption: At-rest and in-transit encryption
• Audit Logging: Comprehensive activity tracking
• Secure Backups: Regular encrypted backups

Performance Optimization

Frontend Optimization

• Code Splitting: Dynamic imports for components
• Image Optimization: Next.js Image component
• Memoization: React.memo, useMemo, useCallback
• Bundle Analysis: Regular bundle size monitoring

Backend Optimization

• Firestore Indexes: Optimized query performance
• Caching Strategy: In-memory and persistent caching
• Function Optimization: Memory and timeout configuration
• Batch Operations: Efficient database writes

Monitoring & Logging

Performance Monitoring

• Firebase Performance: Real-time performance tracking
• Custom Metrics: Business-specific measurements
• Error Tracking: Comprehensive error reporting
• User Analytics: Usage patterns and behavior

Health Checks

• System Health: Service availability monitoring
• Database Health: Connection and query performance
• External APIs: Third-party service monitoring
• Alert System: Automated incident response

Development Workflow

Branch Strategy

main          ← Production branch ├── develop   ← Development integration ├── feature/* ← Feature branches ├── hotfix/*  ← Emergency fixes └── release/* ← Release preparation

Code Quality

• TypeScript: Strict type checking
• ESLint: Code linting and style enforcement
• Prettier: Consistent code formatting
• Husky: Git hooks for quality gates
• Testing: Unit and integration tests