= 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.''