Changes between Version 1 and Version 2 of SouceVersionControlOrganizationRevised

Timestamp:

01/07/26 19:17:58 (8 days ago)

Author:

214004

Comment:

--

SouceVersionControlOrganizationRevised

@@ -1 @@
-== SouceVersionControlOrganizationRevised
-За Контрола на верзиите на изворниот код користевме Github. Работевме на еден branch.
-
-== Структура ==
+= Roadmap FINKI Documentation =
+
+----
+
+== Version Control ==
+
+ * '''Repository:''' GitHub
+ * '''Branching Strategy:''' Single branch development
+ * '''Project Root:''' `roadmap_finki/`
+
+----
+
+== Project Structure ==
+
+{{{
 roadmap_finki/
-├── app/                          # PHP/Laravel код
-├── resources/                     # Frontend (Blade templates)
-├── database/                      # Миграции и seeders
-├── routes/                        # Рутирање
-├── bootstrap/                     # Иницијализација
-├── config/                        # Конфигурација
-├── storage/                       # Датотеки и логови
-├── tests/                         # Тестирање
-├── public/                        # Јавни датотеки (CSS, JS, слики)
-└── vendor/                        # Зависности (Composer)
-
-== Модели ==
-Models/
-├── User.php                    # Кориснички профил
-│   ├── relationships:
-│   │   └── progress()          # HasMany → UserProgress
-│   └── methods:
-│       └── role(), isAdmin()
-│
-├── UserProgress.php            # Напредок на корисник (завршени/во прогрес предмети)
-│   ├── fillable:
-│   │   ├── user_id
-│   │   ├── subject_id
-│   │   ├── study_program_id
-│   │   ├── career_path_id
-│   │   ├── status              # 'completed' | 'in_progress'
-│   │   └── completed_at
-│   └── relationships:
-│       ├── user()              # BelongsTo
-│       ├── subject()            # BelongsTo
-│       ├── studyProgram()       # BelongsTo
-│       └── careerPath()         # BelongsTo
-│
-├── Subject.php                 # Предмет/Курс
-│   ├── attributes:
-│   │   ├── code                # Уникален код (F23L3W004)
-│   │   ├── name                # Англиско име
-│   │   ├── name_mk             # Македонско име
-│   │   ├── year                # 1-4 година
-│   │   ├── semester_type       # 'winter' | 'summer'
-│   │   ├── subject_type        # 'mandatory' | 'elective'
-│   │   ├── credits             # ECTS кредити
-│   │   └── description, instructors, hours
-│   ├── relationships:
-│   │   ├── prerequisites()     # BelongsToMany (self-referencing)
-│   │   ├── requiredBy()        # BelongsToMany (inverse)
-│   │   ├── studyPrograms()     # BelongsToMany
-│   │   ├── careerPaths()       # BelongsToMany
-│   │   └── userProgress()      # HasMany
-│   └── methods:
-│       ├── getSemesterTypeFromCode()   # Извлече W/S од код
-│       ├── hasPrerequisitesMet()       # Проверка на предуслови
-│       └── getDisplayName()            # "CODE - NAME"
-│
-├── StudyProgram.php            # Студиска програма (Computer Science 4-year)
-│   ├── attributes:
-│   │   ├── name_mk             # Македонско име
-│   │   ├── name_en             # Англиско име
-│   │   ├── code                # Уникален код
-│   │   ├── duration_years      # 1-6 години
-│   │   └── cycle               # 'first' | 'second'
-│   ├── relationships:
-│   │   ├── subjects()          # BelongsToMany
-│   │   │   └── pivot: order, type, year, semester_type
-│   │   └── userProgress()      # HasMany
-│   └── methods:
-│       ├── getMandatorySubjects()     # Само задолжителни
-│       ├── getElectiveSubjects()      # Само изборни
-│       └── getDisplayName()           # "NAME (N години)"
-│
-└── CareerPath.php              # Каријерна патека (Full Stack, Data Science, итн.)
-    ├── attributes:
-    │   ├── name                # Име на патека
-    │   └── description
-    ├── relationships:
-    │   └── subjects()          # BelongsToMany
-    │       └── pivot: career_path_subject
-    └── methods:
-        └── getIcon()           # Икона за приказ
-
-
-== Табели во база ==
-users
-├── id, name, email, password
+├── 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
+├── created_at
+├── updated_at
 └── → hasMany(user_progress)
-
-user_progress
-├── id, user_id (FK), subject_id (FK)
-├── study_program_id (FK), career_path_id (FK, nullable)
+}}}
+
+==== 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)
-
-subjects
-├── id, code (unique), name, name_mk
-├── year (1-4), semester_type, subject_type
-├── credits, description, instructions, hours
-└── → belongsToMany(subject_prerequisites)
-    → belongsToMany(study_programs, career_paths)
-    → hasMany(user_progress)
-
-subject_prerequisites
-├── subject_id (FK) → pivot table
-└── prerequisite_id (FK)
-
-study_programs
-├── id, code (unique), name_mk, name_en
-├── duration_years, cycle, description_mk, description_en
-└── → belongsToMany(subjects)
-    → hasMany(user_progress)
-
-study_program_subject (Pivot Table)
-├── id, study_program_id (FK), subject_id (FK)
+}}}
+
+=== 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_paths
-├── id, name, description
-└── → belongsToMany(subjects)
-
-career_path_subject (Pivot Table)
-├── career_path_id (FK)
-└── subject_id (FK)
-
-
-== Контролери ==
-
-Controllers/
-├── RoadmapController.php       # Главна логика за roadmap генерирање
-│   ├── create()               # Приказ на форма за создание
-│   ├── store()                # Зачувување на избори и генерирање
-│   ├── show()                 # Приказ на зачуван roadmap
-│   ├── getSubjectsByProgram() # AJAX - предмети по програма
-│   ├── generateRoadmap()      # Приватна: сортирана листа
-│   └── generateSemesterRoadmap() # Приватна: по години/семестри
-│
-├── SubjectController.php       # CRUD за предметите (Admin)
-│   ├── index()                # Листа со пребарување
-│   ├── create()               # Форма за создание
-│   ├── store()                # Зачувување на предмет
-│   ├── show()                 # Преглед
-│   ├── edit()                 # Форма за уредување
-│   ├── update()               # Ажурирање
-│   └── destroy()              # Бришење
-│
-├── StudyProgramController.php  # CRUD за студиски програми (Admin)
-│   ├── index()                # Листа со пребарување
-│   ├── create()               # Форма за создание
-│   ├── store()                # Зачувување со предметите
-│   ├── show()                 # Преглед со детали
-│   ├── edit()                 # Форма за уредување
-│   ├── update()               # Ажурирање со предметите
-│   └── destroy()              # Бришење
-│
-├── ProfileController.php       # Корисничкиот профил
-│   ├── edit()
-│   ├── update()
-│   └── destroy()
-│
-└── (Others: AuthController, DashboardController, итн.)
+├── 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 ==
 
-Middleware/
-├── Authenticate.php           # Логирана проверка
-├── Admin.php                  # Админ верификација
-└── (Others)
-
-== Requests  ==
-
-
-Requests/
-├── StoreSubjectRequest.php    # Валидација за Subject create/update
-├── StudyProgramRequest.php    # Валидација за StudyProgram
-└── (Others)
+ * '''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 ==
 
-views/roadmap/
-├── create.blade.php           # Форма за создание на roadmap
-│   ├── Step 1: Избор програма и каријерна патека
-│   ├── AJAX: Динамичко вчитување на предмети
-│   ├── Step 2: Избор завршени/во прогрес предмети
-│   ├── Пребарување предмети
-│   ├── Организирани по години
-│   └── JavaScript за обработка
-│
-└── show.blade.php             # Приказ на генериран roadmap
-    ├── Header: Програма и патека
-    ├── Progress Summary: 4 картички
-    ├── ECTS Progress Bar: Визуелен напредок
-    ├── Semester-by-Semester Roadmap:
-    │   ├── За секоја година:
-    │   │   ├── Зимски семестар
-    │   │   └─ Летен семестар
-    │   └── За секој предмет: готово/блокирано
-    ├── Препорачани следни чекори:
-    │   ├─ Готови за запишување (зелено)
-    │   └─ Блокирани (црвено)
-    ├── Завршени предмети
-    └─ Во прогрес предмети
-
-
-
-== Рути во апликацијата ==
-
-
-routes/
-├── web.php                    # Главни рути
-│   ├── GET / → Welcome
-│   ├── GET /dashboard → Dashboard
-│   ├── GET /roadmap/create → RoadmapController@create
-│   ├── POST /roadmap → RoadmapController@store
-│   ├── GET /roadmap → RoadmapController@show
-│   ├── GET /api/study-program/{id}/subjects → RoadmapController@getSubjectsByProgram
-│   ├── resource /subjects → SubjectController (админ)
-│   ├── resource /study-programs → StudyProgramController (админ)
-│   └── (Others: profile, auth)
-│
-├── auth.php                   # Автентицирани рути
-│   ├── Регистрирање
-│   ├── Логирање
-│   ├── Password reset
-│   └── Email verification
-│
-
+=== 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.''