​
Overview

The Mapademics platform is built around a comprehensive data model that organizes educational content, job market data, and extracted skills in a hierarchical, multi-tenant structure. This reference provides technical administrators with a complete understanding of how data is organized, related, and processed within the platform. Understanding this data model is essential for:
  • Data import planning and bulk operations
  • Integration with external systems
  • Troubleshooting data relationships
  • Configuring skills processing pipelines
  • Understanding report data sources

​
Core Architecture Principles

​
Multi-Tenant Organization Structure

Every entity in Mapademics belongs to an Organization, which serves as the primary tenant boundary. Organizations provide complete data isolation and independent configuration management. 
Organization (Root Tenant)
├── Users & Authentication
├── Educational Data (Programs, Courses, Sections, Instructors)
├── Job Market Data (Employers, Custom Jobs)
├── Skills Processing Configuration
└── Batch Processing Jobs

​
Section-Based Skills Architecture

​
Soft Deletion Pattern

All core entities use soft deletion with deletedAt timestamps, ensuring data integrity and audit capabilities. Deleted items remain in the database but are excluded from normal queries.

​
Educational Data Hierarchy

​
Organization → Program → Course → Course Section

The educational data follows a clear hierarchical structure:
LevelEntityPurposeKey Relationships
1OrganizationTenant boundaryRoot of all data
2ProgramDegree/Certificate programsContains ordered courses
3CourseIndividual academic coursesHas multiple sections
4Course SectionSpecific course offeringsInstructor + skills

​
Program Structure

Programs represent degree programs, certificates, or other educational pathways with specific Classification of Instructional Programs (CIP) codes. Key Fields:
  • name - Program title
  • code - Internal program identifier
  • cipCode - Standard CIP classification
  • courseOrder - Array defining course sequence
  • metadata - JSON metadata storage
  • auditTrail - JSON audit logging
Relationships:
  • Many-to-many with Courses (supports shared courses across programs)
  • Belongs to single Organization

​
Course Structure

Courses are the fundamental academic units that can appear in multiple programs. Key Fields:
  • name - Course title
  • code - Course identifier (e.g., “CS101”)
  • description - Course description
  • defaultSectionId - Primary section reference
  • syllabusHref - Legacy syllabus link
  • skills - JSON array of extracted skills
Relationships:
  • Many-to-many with Programs
  • One-to-many with Course Sections
  • Belongs to single Organization

​
Course Section Structure

Course Sections represent specific offerings of a course, typically with unique instructors and syllabi. Key Fields:
  • name - Section identifier
  • description - Section-specific description
  • syllabusHref - Section-specific syllabus
  • skills - JSON array of ParsedSkill objects
  • metadata - JSON metadata storage
  • auditTrail - JSON audit logging
Relationships:
  • Belongs to one Course
  • Optional relationship with Instructor
  • Many-to-many with Stackable Credentials
  • Belongs to single Organization

​
Instructor Structure

Instructors are faculty members who teach course sections. Key Fields:
  • name - Instructor full name
  • email - Contact email
  • details - Additional instructor information
Relationships:
  • One-to-many with Course Sections
  • Belongs to single Organization

​
Job Market Data Structure

​
Employer → Custom Job Hierarchy

Job market data is organized to support both national labor statistics and institution-specific employer relationships.
EntityPurposeSkills Source
EmployerPartner organizationsVia Custom Jobs
Custom JobSpecific job descriptionsDirect skills extraction

​
Employer Structure

Employers represent partner organizations or companies that provide job descriptions for analysis. Key Fields:
  • name - Company/organization name
  • description - Employer description
Relationships:
  • One-to-many with Custom Jobs
  • Belongs to single Organization

​
Custom Job Structure

Custom Jobs contain specific job descriptions that undergo skills extraction processing. Key Fields:
  • name - Job title
  • description - Job description
  • jobDescriptionHref - Document link
  • skills - JSON array of extracted skills
Relationships:
  • Belongs to one Employer (optional)
  • Belongs to single Organization

​
Skills Data Structure

​
ParsedSkill Type Definition

Skills across the platform use a consistent ParsedSkill structure: 
type ParsedSkill = {
  skillId: number;        // OST (Open Skills Taxonomy) ID
  level: number;          // Proficiency level (1-5)
  mode: "explicit" | "implicit"; // How skill was identified
  source: "user" | "auto";       // Manual vs automated extraction
  rationale?: string;     // AI reasoning (optional)
  active: boolean;        // Whether skill is active
}

​
Skills Storage Locations

Skills are stored as JSON arrays in multiple locations:
EntitySkills FieldPrimary Use
Course SectionskillsPrimary skills storage (current model)
CourseskillsLegacy support (being migrated)
Custom JobskillsJob requirements analysis

​
Open Skills Taxonomy (OST) Integration

All skills reference the Open Skills Taxonomy, a standardized framework providing:
  • Unique skill identifiers
  • Hierarchical skill categories
  • Standardized skill descriptions
  • Cross-industry skill mapping

​
Stackable Credentials System

​
Many-to-Many Course Section Relationships

Stackable Credentials represent micro-credentials or certificates that span multiple course sections. Key Fields:
  • name - Credential title
  • code - Credential identifier
  • description - Credential description
  • metadata - JSON metadata storage
Relationships:
  • Many-to-many with Course Sections
  • Belongs to single Organization
Use Cases:
  • Industry certifications
  • Professional development tracks
  • Competency-based credentials
  • Cross-program skill pathways

​
Batch Processing Architecture

​
Processing Job Hierarchy

All heavy computational work is handled through Trigger.dev batch processing jobs with a consistent parent-child pattern: 
Batch Job (Parent)
├── Processing Item 1 (Child)
├── Processing Item 2 (Child)
└── Processing Item N (Child)

​
Syllabus Processing Jobs

Structure:
  • SyllabusProcessingBatchJob (parent)
    • SyllabusProcessingItems (children)
Key Features:
  • Section-based processing (new model)
  • Course-based processing (legacy support)
  • Prompt configuration tracking
  • Status monitoring and error handling

​
Job Description Processing Jobs

Structure:
  • JobDescriptionProcessingBatchJob (parent)
    • JobDescriptionProcessingItems (children)
Processing Flow:
  1. Custom job document analysis
  2. Skills extraction using AI
  3. Manual review for uncertain classifications
  4. Final skills attachment to job records

​
SOC Skills Mapping Jobs

Structure:
  • SocClassificationBatchJob (parent)
    • SOCSkillsMapping records (children)
Purpose:
  • Maps Standard Occupational Classification (SOC) codes to OST skills
  • Enables job market alignment analysis
  • Supports career pathway recommendations

​
AI Processing Configuration

​
Organization-Level Model Configuration

Each organization maintains a ModelConfiguration record controlling AI model selection and parameters: Syllabus Processing Models:
  • Structure extraction model & temperature
  • Skills extraction model & temperature
  • Skills grading model & temperature
  • Cognitive skills model & temperature
Job Description Processing Models:
  • Structure extraction model & temperature
  • Skills extraction model & temperature
  • Skills grading model & temperature
SOC Classification Models:
  • Classification model & temperature

​
Custom Prompt Templates

Organizations can override default AI prompts with PromptTemplate records: Structure:
  • pipeline - “syllabus” or “job-description”
  • step - Processing stage identifier
  • version - Template version
  • instructionPrompt - Custom prompt text
  • isActive - Template status

​
Bulk Data Import System

​
Import Process Structure

BulkImport records track large-scale data import operations: Key Fields:
  • filename - Source file name
  • totalItems - Expected import count
  • processedItems - Current progress
  • status - Processing state
  • conflictResolutions - User decisions for conflicts
  • results - Detailed import outcomes

​
Conflict Resolution System

The bulk import system handles data conflicts through structured resolution types: 
type ConflictResolution = "skip" | "replace" | "create_new";

interface BulkImportConflictResolutions {
  programs: Record<string, ConflictResolution>;
  courses: Record<string, ConflictResolution>;
  instructors: Record<string, ConflictResolution>;
  courseSections: Record<string, ConflictResolution>;
  credentials: Record<string, ConflictResolution>;
}

​
Authentication & User Management

​
User Organization Relationships

Users belong to organizations with role-based access control: User Roles:
  • USER - Standard organization member
  • ADMIN - Organization administrator
  • MAPADEMICS_ADMIN - Platform administrator
Dual Organization Support:
  • organization - Primary organization membership
  • maOrganization - Mapademics admin organization (for staff)

​
Authentication Models

Supported Authentication:
  • NextAuth.js with multiple providers
  • Credentials provider with password storage in IdPUser
  • OAuth providers (GitHub, etc.)
  • Session management with JWT tokens

​
Data Integrity & Constraints

​
Required Relationships

Critical Foreign Keys:
  • All entities MUST belong to an organization
  • Course sections MUST belong to a course
  • Processing items MUST belong to a batch job
  • Skills MUST reference valid OST identifiers

​
Unique Constraints

Important Uniqueness Rules:
  • Organization publicApiKey is globally unique
  • User email is globally unique
  • SOC code mapping is unique per SOC code
  • Prompt templates are unique per organization+pipeline+step

​
JSON Field Validation

Structured JSON Fields:
  • skills arrays must contain valid ParsedSkill objects
  • metadata follows organization-specific schemas
  • auditTrail maintains chronological change records

​
Performance Considerations

​
Indexing Strategy

Key Database Indexes:
  • Organization ID on all tenant-scoped entities
  • Skills processing batch job status
  • User email for authentication lookups
  • SOC processing status for review workflows

​
Query Optimization

Best Practices:
  • Always filter by organization ID first
  • Use soft deletion filters consistently
  • Leverage JSON indexing for skills queries
  • Cache OST skills data for performance

​
Migration & Compatibility

​
Section-Based Skills Migration

The platform supports both legacy course-level skills and modern section-level skills: Migration Process:
  1. Legacy courses with skills create a “Main Section”
  2. Skills are copied to the new section
  3. Course maintains skills for backward compatibility
  4. New workflows use section-based skills exclusively
Compatibility Notes:
  • Existing reports work with both models
  • API endpoints support both access patterns
  • Bulk imports create sections automatically
This data model provides the foundation for all Mapademics functionality, from basic data management to advanced AI-powered skills analysis and career pathway recommendations.