Roadmap FINKI Documentation

---

Version Control

• Repository: GitHub
• Branching Strategy: Single branch development
• Project Root: roadmap_finki/

---

Project Structure

roadmap_finki/
├── app/                          # PHP/Laravel application code
├── resources/                    # Frontend (Blade templates)
├── database/                     # Database migrations and seeders
├── routes/                       # Application routing
├── bootstrap/                    # Application initialization
├── config/                       # Configuration files
├── storage/                      # File storage and logs
├── tests/                        # Test suite
├── public/                       # Public assets (CSS, JS, images)
└── vendor/                       # Composer dependencies

---

Data Models

User.php

Manages user profiles and authentication.

• Relationships:
  • progress() - HasMany → UserProgress
• Methods:
  • role() - Returns user role
  • isAdmin() - Checks admin privileges

UserProgress.php

Tracks student progress through subjects (completed/in-progress).

• Fillable Attributes:
  • user_id - Foreign key to users table
  • subject_id - Foreign key to subjects table
  • study_program_id - Foreign key to study programs
  • career_path_id - Foreign key to career paths (nullable)
  • status - Enum: 'completed' | 'in_progress'
  • completed_at - Timestamp (nullable)
• Relationships:
  • user() - BelongsTo User
  • subject() - BelongsTo Subject
  • studyProgram() - BelongsTo StudyProgram
  • careerPath() - BelongsTo CareerPath

Subject.php

Represents academic subjects/courses.

• Attributes:
  • code - Unique identifier (e.g., F23L3W004)
  • name - English name
  • name_mk - Macedonian name
  • year - Academic year (1-4)
  • semester_type - Enum: 'winter' | 'summer'
  • subject_type - Enum: 'mandatory' | 'elective'
  • credits - ECTS credits
  • description, instructors, hours - Additional metadata
• Relationships:
  • prerequisites() - BelongsToMany (self-referencing)
  • requiredBy() - BelongsToMany (inverse prerequisites)
  • studyPrograms() - BelongsToMany StudyProgram
  • careerPaths() - BelongsToMany CareerPath
  • userProgress() - HasMany UserProgress
• Methods:
  • getSemesterTypeFromCode() - Extracts W/S from subject code
  • hasPrerequisitesMet() - Validates prerequisite completion
  • getDisplayName() - Returns formatted "CODE - NAME"

StudyProgram.php

Represents academic study programs (e.g., Computer Science 4-year).

• Attributes:
  • name_mk - Macedonian name
  • name_en - English name
  • code - Unique identifier
  • duration_years - Program duration (1-6 years)
  • cycle - Enum: 'first' | 'second'
• Relationships:
  • subjects() - BelongsToMany Subject
    • Pivot fields: order, type, year, semester_type
  • userProgress() - HasMany UserProgress
• Methods:
  • getMandatorySubjects() - Returns only mandatory subjects
  • getElectiveSubjects() - Returns only elective subjects
  • getDisplayName() - Returns formatted "NAME (N years)"

CareerPath.php

Represents career specialization paths (e.g., Full Stack, Data Science).

• Attributes:
  • name - Career path name
  • description - Detailed description
• Relationships:
  • subjects() - BelongsToMany Subject
    • Pivot table: career_path_subject
• Methods:
  • getIcon() - Returns icon for display

---

Database Schema

Core Tables

users

├── id (PK)
├── name
├── email
├── password
├── role (enum: 'admin', 'user')
├── created_at
├── updated_at
└── → hasMany(user_progress)

subjects

├── id (PK)
├── code (unique)
├── name
├── name_mk
├── year (1-4)
├── semester_type (winter/summer)
├── subject_type (mandatory/elective)
├── credits
├── description
├── instructors
├── hours
└── → belongsToMany(subject_prerequisites, study_programs, career_paths)
    → hasMany(user_progress)

study_programs

├── id (PK)
├── code (unique)
├── name_mk
├── name_en
├── duration_years
├── cycle (first/second)
├── description_mk
├── description_en
└── → belongsToMany(subjects)
    → hasMany(user_progress)

career_paths

├── id (PK)
├── name
├── description
└── → belongsToMany(subjects)

user_progress

├── id (PK)
├── user_id (FK → users)
├── subject_id (FK → subjects)
├── study_program_id (FK → study_programs)
├── career_path_id (FK → career_paths, nullable)
├── status (enum: 'completed', 'in_progress')
├── completed_at (timestamp, nullable)
└── → belongsTo(user, subject, study_program, career_path)

Pivot Tables

subject_prerequisites

Self-referencing table for subject dependencies.

├── subject_id (FK → subjects)
└── prerequisite_id (FK → subjects)

study_program_subject

Links study programs to subjects with additional metadata.

├── id (PK)
├── study_program_id (FK → study_programs)
├── subject_id (FK → subjects)
├── type (mandatory/elective)
├── year
├── semester_type
├── order
└── timestamps

career_path_subject

Links career paths to relevant subjects.

├── career_path_id (FK → career_paths)
└── subject_id (FK → subjects)

---

Controllers

RoadmapController.php

Primary controller for roadmap generation logic.

• create() - Display roadmap creation form
• store() - Save user selections and generate roadmap
• show() - Display generated roadmap
• getSubjectsByProgram() - AJAX endpoint for dynamic subject loading
• generateRoadmap() - Private: Generate sorted subject list
• generateSemesterRoadmap() - Private: Organize subjects by year/semester

SubjectController.php

Standard resource controller for subject management (Admin only).

• index() - List subjects with search functionality
• create() - Display subject creation form
• store() - Save new subject
• show() - Display subject details
• edit() - Display subject edit form
• update() - Update existing subject
• destroy() - Delete subject

StudyProgramController.php

Standard resource controller for study program management (Admin only).

• index() - List programs with search functionality
• create() - Display program creation form
• store() - Save new program with subjects
• show() - Display program details
• edit() - Display program edit form
• update() - Update existing program with subjects
• destroy() - Delete program

ProfileController.php

Manages user profile operations.

• edit() - Display profile edit form
• update() - Update profile information
• destroy() - Delete user account

---

Middleware

• Authenticate.php - Verifies user authentication
• Admin.php - Verifies admin privileges for protected routes

---

Request Validation

• StoreSubjectRequest.php - Validation rules for subject creation and updates
• StudyProgramRequest.php - Validation rules for study program operations

---

Views

roadmap/create.blade.php

Two-step roadmap creation form.

Step 1: Program and Career Path Selection

• Select study program from dropdown
• Select career path (optional)
• AJAX dynamic loading of subjects based on selection

Step 2: Progress Selection

• Mark completed subjects
• Mark in-progress subjects
• Search/filter subjects
• Subjects organized by academic year
• JavaScript for form handling and validation

roadmap/show.blade.php

Displays generated personalized roadmap.

Components:

• Header - Selected program and career path
• Progress Summary - Four summary cards with statistics
• ECTS Progress Bar - Visual progress indicator
• Semester-by-Semester Roadmap
  • Organized by academic year
  • Winter and summer semesters
  • Subject status indicators (completed/blocked/available)
• Recommended Next Steps
  • Available subjects (green) - prerequisites met
  • Blocked subjects (red) - prerequisites not met
• Completed Subjects List
• In-Progress Subjects List

---

Application Routes

web.php

Main application routes.

GET  /                                              → Welcome page
GET  /dashboard                                      → User dashboard
GET  /roadmap/create                                 → RoadmapController@create
POST /roadmap                                        → RoadmapController@store
GET  /roadmap                                        → RoadmapController@show
GET  /api/study-program/{id}/subjects                → RoadmapController@getSubjectsByProgram

Admin Routes (require admin middleware):

resource /subjects                                   → SubjectController
resource /study-programs                             → StudyProgramController

User Routes:

resource /profile                                    → ProfileController

auth.php

Authentication routes.

• User registration
• User login/logout
• Password reset
• Email verification

---

Key Features

1. Prerequisite Tracking - Automatic validation of subject prerequisites
2. Progress Visualization - Visual representation of academic progress
3. Career Path Integration - Tailored recommendations based on career goals
4. ECTS Credit Tracking - Monitor credit completion toward degree requirements
5. Semester Planning - Organized view of subjects by semester
6. Admin Dashboard - Full CRUD operations for subjects and programs
7. AJAX Integration - Dynamic form updates without page refresh

---

Technical Stack

• Backend: PHP with Laravel framework
• Frontend: Blade templating engine
• Database: Relational database (MySQL/PostgreSQL)
• JavaScript: For dynamic interactions and AJAX
• CSS: For styling and responsive design

---

Access Control

• Public Access: Welcome page, registration, login
• Authenticated Users: Dashboard, roadmap creation/viewing, profile management
• Admin Users: All user features plus subject/program management

---

For more information, please contact the development team or refer to the project repository.