# skillspan/back-end architecture

> Architecture diagram of the GitHub repository skillspan/back-end, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skillspan/back-end
- Repository: https://github.com/skillspan/back-end

## Overview

SkillSpan is a Laravel API for learner skills-readiness and organization participation. The principal learner workflow is account verification, profile and skill assessment, then career-role readiness calculation and result retrieval. Organizations register with proof for admin review. The tree also identifies project matching, assistant/conversation, intelligence, mentoring, and notification capabilities. Some service implementations and routes were not sampled, so those subsystems are shown without speculative internal call chains.

Main entry points: [`routes/api.php`](https://github.com/skillspan/back-end/blob/main/routes/api.php) (API routes), [`app/Services/AuthService.php`](https://github.com/skillspan/back-end/blob/main/app/Services/AuthService.php) (Authentication service), [`app/Services/Readiness/ReadinessService.php`](https://github.com/skillspan/back-end/blob/main/app/Services/Readiness/ReadinessService.php) (Readiness calculation), [`app/Http/Controllers/Api/Internal/BaselineItemsController.php`](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/Internal/BaselineItemsController.php) (Baseline item feed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts and access"]
  node_auth_controller["Authentication API<br/>[AuthController.php]"]
  node_auth_service["Authentication service<br/>[AuthService.php]"]
  node_admin_review["Organization review"]
  node_account_data[("Account records")]
  node_admin_web["Admin review panel"]
end

subgraph group_learning["Skills and readiness"]
  node_baseline_controller["Baseline assessment API"]
  node_baseline_service["Baseline assessment"]
  node_baseline_items["Baseline item feed"]
  node_readiness_controller["Readiness API"]
  node_readiness_service["Readiness calculation"]
  node_skill_match_controller["Skill match API"]
  node_skill_match_service["Skill match algorithm"]
  node_learning_data[("Learning records")]
end

subgraph group_opportunities["Projects and careers"]
  node_career_controller["Career roles API"]
  node_project_controller["Project matching API"]
  node_project_service["Project matching"]
  node_project_data[("Career and project records")]
end

subgraph group_engagement["Guidance and collaboration"]
  node_assistant_controller["Assistant API"]
  node_assistant_service["Assistant service"]
  node_conversation_controller["Conversation API"]
  node_mentor_controller["Mentor connections API"]
  node_engagement_data[("Engagement records")]
end

subgraph group_platform["Shared platform"]
  node_api_routes["API routes<br/>[api.php]"]
end

node_learner(("Learner"))
node_organization(("Organization"))
node_admin(("Administrator"))
node_email["Email service"]
node_fastapi["FastAPI service"]

node_learner -->|"sends API requests"| node_api_routes
node_organization -->|"sends API requests"| node_api_routes
node_admin -->|"reviews organizations"| node_api_routes
node_api_routes -->|"routes authentication"| node_auth_controller
node_auth_controller -->|"delegates account actions"| node_auth_service
node_auth_service -->|"reads and writes"| node_account_data
node_auth_service -->|"sends verification"| node_email
node_api_routes -->|"routes assessment requests"| node_baseline_controller
node_baseline_controller -->|"handles assessment"| node_baseline_service
node_baseline_service -->|"stores assessment data"| node_learning_data
node_api_routes -->|"routes calculation requests"| node_readiness_controller
node_readiness_controller -->|"requests calculation"| node_readiness_service
node_readiness_service -->|"requests readiness calculation"| node_fastapi
node_readiness_service -->|"persists results"| node_learning_data
node_api_routes -->|"routes skill-match requests"| node_skill_match_controller
node_skill_match_controller -->|"calculates match score"| node_skill_match_service
node_api_routes -->|"routes internal item requests"| node_baseline_items
node_baseline_items -->|"reads assessment items"| node_learning_data
node_fastapi -->|"fetches assessment items"| node_baseline_items
node_api_routes -->|"routes career requests"| node_career_controller
node_career_controller -->|"reads career roles"| node_project_data
node_api_routes -->|"routes project requests"| node_project_controller
node_project_controller -->|"requests matching"| node_project_service
node_project_service -->|"reads project records"| node_project_data
node_api_routes -->|"routes assistant requests"| node_assistant_controller
node_assistant_controller -->|"requests assistance"| node_assistant_service
node_api_routes -->|"routes conversation requests"| node_conversation_controller
node_conversation_controller -->|"manages conversations"| node_engagement_data
node_api_routes -->|"routes mentor requests"| node_mentor_controller
node_mentor_controller -->|"manages connections"| node_engagement_data
node_admin -->|"signs into review panel"| node_admin_web
node_admin_review -->|"updates organization records"| node_account_data
node_admin_review -->|"sends review notices"| node_email

click node_api_routes "https://github.com/skillspan/back-end/blob/main/routes/api.php"
click node_auth_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_auth_service "https://github.com/skillspan/back-end/blob/main/app/Services/AuthService.php"
click node_admin_review "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/Admin/OrganizationController.php"
click node_account_data "https://github.com/skillspan/back-end/tree/main/app/Models"
click node_baseline_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/BaselineAssessmentController.php"
click node_baseline_service "https://github.com/skillspan/back-end/blob/main/app/Services/Baseline/BaselineAssessmentService.php"
click node_baseline_items "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/Internal/BaselineItemsController.php"
click node_readiness_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ReadinessController.php"
click node_readiness_service "https://github.com/skillspan/back-end/blob/main/app/Services/Readiness/ReadinessService.php"
click node_skill_match_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/SkillMatchController.php"
click node_skill_match_service "https://github.com/skillspan/back-end/blob/main/app/Services/Readiness/SkillMatchService.php"
click node_learning_data "https://github.com/skillspan/back-end/tree/main/app/Models"
click node_career_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/CareerRoleController.php"
click node_project_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ProjectMatchingController.php"
click node_project_service "https://github.com/skillspan/back-end/blob/main/app/Services/Projects/ProjectMatchingService.php"
click node_project_data "https://github.com/skillspan/back-end/tree/main/app/Models"
click node_assistant_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/AssistantController.php"
click node_assistant_service "https://github.com/skillspan/back-end/blob/main/app/Services/Assistant/AssistantService.php"
click node_conversation_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ConversationController.php"
click node_mentor_controller "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/MentorStudentController.php"
click node_engagement_data "https://github.com/skillspan/back-end/tree/main/app/Models"
click node_admin_web "https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Web/AdminAuthController.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_controller,node_auth_service,node_admin_review,node_account_data,node_admin_web toneBlue
class node_baseline_controller,node_baseline_service,node_baseline_items,node_readiness_controller,node_readiness_service,node_skill_match_controller,node_skill_match_service,node_learning_data toneAmber
class node_career_controller,node_project_controller,node_project_service,node_project_data,node_fastapi toneMint
class node_assistant_controller,node_assistant_service,node_conversation_controller,node_mentor_controller,node_engagement_data toneRose
class node_api_routes,node_learner,node_organization,node_admin,node_email toneIndigo
```

## Components

### Accounts and access

- [Authentication API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [Authentication service](https://github.com/skillspan/back-end/blob/main/app/Services/AuthService.php): `app/Services/AuthService.php`
- [Organization review](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/Admin/OrganizationController.php): `app/Http/Controllers/Api/Admin/OrganizationController.php`
- [Account records](https://github.com/skillspan/back-end/tree/main/app/Models): `app/Models`
- [Admin review panel](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Web/AdminAuthController.php): `app/Http/Controllers/Web/AdminAuthController.php`

### Skills and readiness

- [Baseline assessment API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/BaselineAssessmentController.php): `app/Http/Controllers/Api/BaselineAssessmentController.php`
- [Baseline assessment](https://github.com/skillspan/back-end/blob/main/app/Services/Baseline/BaselineAssessmentService.php): `app/Services/Baseline/BaselineAssessmentService.php`
- [Baseline item feed](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/Internal/BaselineItemsController.php): `app/Http/Controllers/Api/Internal/BaselineItemsController.php`
- [Readiness API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ReadinessController.php): `app/Http/Controllers/Api/ReadinessController.php`
- [Readiness calculation](https://github.com/skillspan/back-end/blob/main/app/Services/Readiness/ReadinessService.php): `app/Services/Readiness/ReadinessService.php`
- [Skill match API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/SkillMatchController.php): `app/Http/Controllers/Api/SkillMatchController.php`
- [Skill match algorithm](https://github.com/skillspan/back-end/blob/main/app/Services/Readiness/SkillMatchService.php): `app/Services/Readiness/SkillMatchService.php`
- [Learning records](https://github.com/skillspan/back-end/tree/main/app/Models): `app/Models`

### Projects and careers

- [Career roles API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/CareerRoleController.php): `app/Http/Controllers/Api/CareerRoleController.php`
- [Project matching API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ProjectMatchingController.php): `app/Http/Controllers/Api/ProjectMatchingController.php`
- [Project matching](https://github.com/skillspan/back-end/blob/main/app/Services/Projects/ProjectMatchingService.php): `app/Services/Projects/ProjectMatchingService.php`
- [Career and project records](https://github.com/skillspan/back-end/tree/main/app/Models): `app/Models`

### Guidance and collaboration

- [Assistant API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/AssistantController.php): `app/Http/Controllers/Api/AssistantController.php`
- [Assistant service](https://github.com/skillspan/back-end/blob/main/app/Services/Assistant/AssistantService.php): `app/Services/Assistant/AssistantService.php`
- [Conversation API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/ConversationController.php): `app/Http/Controllers/Api/ConversationController.php`
- [Mentor connections API](https://github.com/skillspan/back-end/blob/main/app/Http/Controllers/Api/MentorStudentController.php): `app/Http/Controllers/Api/MentorStudentController.php`
- [Engagement records](https://github.com/skillspan/back-end/tree/main/app/Models): `app/Models`

### Shared platform

- [API routes](https://github.com/skillspan/back-end/blob/main/routes/api.php): `routes/api.php`

### Other components

- **Learner**
- **Organization**
- **Administrator**
- **Email service**
- **FastAPI service**

## Connections

- Learner → API routes: sends API requests
- Organization → API routes: sends API requests
- Administrator → API routes: reviews organizations
- API routes → Authentication API: routes authentication
- Authentication API → Authentication service: delegates account actions
- Authentication service → Account records: reads and writes
- Authentication service → Email service: sends verification
- API routes → Baseline assessment API: routes assessment requests
- Baseline assessment API → Baseline assessment: handles assessment
- Baseline assessment → Learning records: stores assessment data
- API routes → Readiness API: routes calculation requests
- Readiness API → Readiness calculation: requests calculation
- Readiness calculation → FastAPI service: requests readiness calculation
- Readiness calculation → Learning records: persists results
- API routes → Skill match API: routes skill-match requests
- Skill match API → Skill match algorithm: calculates match score
- API routes → Baseline item feed: routes internal item requests
- Baseline item feed → Learning records: reads assessment items
- FastAPI service → Baseline item feed: fetches assessment items
- API routes → Career roles API: routes career requests
- Career roles API → Career and project records: reads career roles
- API routes → Project matching API: routes project requests
- Project matching API → Project matching: requests matching
- Project matching → Career and project records: reads project records
- API routes → Assistant API: routes assistant requests
- Assistant API → Assistant service: requests assistance
- API routes → Conversation API: routes conversation requests
- Conversation API → Engagement records: manages conversations
- API routes → Mentor connections API: routes mentor requests
- Mentor connections API → Engagement records: manages connections
- Administrator → Admin review panel: signs into review panel
- Organization review → Account records: updates organization records
- Organization review → Email service: sends review notices