# humayranuha/group_sync architecture

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

- Interactive diagram: https://gitdiagram.com/humayranuha/group_sync
- Repository: https://github.com/humayranuha/group_sync

## Overview

1. **High-level shape**
   GroupSync is organized as a three-part system: a **Laravel backend** for core domain logic and persistence, a **JavaScript frontend** for role-based user interaction, and a small **Node/Express auxiliary service** under `backend/`. The main runtime boundary is between the browser UI and the Laravel API; the Node service appears to support a specialized side function rather than host the main app.

2. **Frontend application boundary**
   The UI is a modular single-page style frontend with separate experiences for **students, professors, admins, and public users**. It has dedicated layouts (`AuthLayout`, `MainLayout`, `ProfessorLayout`, `StudentLayout`) and page groups for each role, which makes role-based navigation a first-class architectural concern.

3. **Frontend component structure**
   The frontend is split into reusable layers: `components/` for analytics, charts, common widgets, forms, and layout chrome; `services/` for API-facing logic; `store/` for client state; and `utils/` for helpers, formatting, validation, and PDF generation. This suggests the UI is not just static pages but a data-driven client that orchestrates multiple backend calls.

4. **Backend application boundary**
   The Laravel app under `code/app` is the system of record. It exposes HTTP endpoints through `routes/api.php` and `routes/web.php`, with controllers such as `ApiController`, `DashboardController`, and `NodeEmailController`. The backend owns authentication, domain rules, score calculation, reporting data, and administrative operations.

5. **Core domain model**
   The persistent model centers on `User`, `Course`, `Group`, `Assignment`, `PeerReview`, `ContributionScore`, `Attendance`, `WorkingHour`, `Notification`, and `AuditLog`. The migrations show many-to-many links for `course_student` and `group_members`, which means the system models both course enrollment and group membership explicitly rather than embedding them in single tables.

6. **Contribution scoring pipeline**
   A key backend workflow is the weighted contribution score. The scheduled Artisan command `CalculateContributionScores.php` indicates periodic aggregation of multiple signals: GitHub activity, attendance, logged working hours, and peer reviews. The resulting `ContributionScore` record is then consumed by dashboards, alerts, and professor reports.

7. **Collaboration and course management flow**
   Professors create courses and assignments, enroll students, and inspect all groups within a course. Students create or join groups using invitation codes, then connect a GitHub repository for activity tracking. This flow is supported by the group/course models and by frontend pages for course management, group details, and repository connection.

8. **Analytics and reporting**
   The product has a dedicated analytics layer for visualizing contribution patterns, low performers, activity consistency, commit trends, and team comparisons. On the frontend these are represented by analytics/chart components and professor/student analytics pages; on the backend the data is prepared from the scoring and domain tables. Report generation is a separate concern, with a professor PDF report page and a shared `pdfGenerator` utility on the client side.

9. **Authentication and role control**
   Authentication is role-based and appears to use Laravel’s token/session stack with Sanctum configured in `config/sanctum.php`. The frontend has protected routes and role-specific layouts, while the backend has user/account management plus admin controls. This makes authorization a major boundary: public pages are separate from authenticated student, professor, and admin areas.

10. **Notifications, auditability, and operational data**
   The presence of `Notification` and `AuditLog` models, plus migrations for logs and sessions, shows that the system tracks user-visible alerts and admin-facing history. This supports feedback on score changes, pending peer reviews, and system activity monitoring, which are part of the admin and professor experiences.

11. **External integrations**
   GitHub is the main external data source, used to capture repository activity for contribution analytics. Email is also a supporting integration, reflected by `NodeEmailController` and mail config. There is also an `aiService` on the frontend, which suggests AI-assisted feedback is a separate integration surface rather than core domain logic.

12. **Deployment/runtime layout**
   The repository contains both `code/public/frontend` and a parallel top-level `frontend/` tree with the same structure, implying the frontend is maintained as a standalone artifact that is also published into Laravel’s public web root. Runtime-wise, the backend is PHP/Laravel with MySQL, while the frontend is a static JS application built with modern tooling such as Vite/Tailwind, and the auxiliary Node server runs separately when needed.

13. **What an architecture diagram should emphasize**
   The most important boxes are: **Browser UI**, **Laravel API/domain layer**, **MySQL database**, **GitHub API**, and the **score/reporting pipeline**. The critical arrows are: user actions from the role-based frontend to Laravel endpoints, Laravel writes/reads from MySQL, Laravel periodically recalculates contribution scores, and GitHub activity feeds into that scoring process. The Node service should be shown as a secondary integration component, not the primary backend.

Main entry points: [`code/app/Http/Controllers/ApiController.php`](https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/ApiController.php) (API Controller), [`code/public/frontend/index.html`](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/index.html) (Frontend App), [`code/app/Models/ContributionScore.php`](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/ContributionScore.php) (Contribution Scores), [`code/app/Console/Commands/CalculateContributionScores.php`](https://github.com/humayranuha/group_sync/blob/main/code/app/Console/Commands/CalculateContributionScores.php) (Score Job)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_frontend_app["Frontend App<br/>SPA UI<br/>[index.html]"]
  node_frontend_services["API Services<br/>frontend service layer<br/>[api.js]"]
  node_frontend_layouts["Role Layouts<br/>navigation shell<br/>[MainLayout.js]"]
  node_frontend_components["UI Components<br/>shared widgets<br/>[Card.js]"]
  node_frontend_state["Client State<br/>state store<br/>[state.js]"]
  node_frontend_utils["Client Utils<br/>helpers<br/>[pdfGenerator.js]"]
end

subgraph group_backend["Laravel Backend"]
  node_routes_api["API Routes<br/>http routes<br/>[api.php]"]
  node_routes_web["Web Routes<br/>http routes<br/>[web.php]"]
  node_api_controller["API Controller<br/>[ApiController.php]"]
  node_dashboard_controller["Dashboard Controller"]
  node_email_controller["Email Controller<br/>integration controller"]
  node_score_job["Score Job<br/>artisan command"]
end

subgraph group_data["Data Model"]
  node_user_model[("Users<br/>domain model<br/>[User.php]")]
  node_course_model[("Courses<br/>domain model<br/>[Course.php]")]
  node_group_model[("Groups<br/>domain model<br/>[Group.php]")]
  node_assignment_model[("Assignments<br/>domain model<br/>[Assignment.php]")]
  node_peer_review_model[("Peer Reviews<br/>domain model<br/>[PeerReview.php]")]
  node_score_model[("Contribution Scores<br/>analytics model")]
end

subgraph group_integrations["External Services"]
  node_node_service["Node Service<br/>aux service<br/>[server.js]"]
  node_github_api(("GitHub<br/>external api"))
  node_email_provider(("Email<br/>external service"))
  node_mysql[("MySQL<br/>database")]
end

node_browser(("Browser<br/>client runtime"))

node_browser -->|"uses"| node_frontend_app
node_frontend_app -->|"navigates"| node_frontend_layouts
node_frontend_app -->|"renders"| node_frontend_components
node_frontend_app -->|"calls"| node_frontend_services
node_frontend_app -->|"shares state"| node_frontend_state
node_frontend_app -->|"uses"| node_frontend_utils
node_frontend_services -->|"requests"| node_routes_api
node_frontend_app -.->|"loads views"| node_routes_web
node_routes_api -->|"dispatches"| node_api_controller
node_routes_web -->|"dispatches"| node_dashboard_controller
node_api_controller -->|"reads/writes"| node_user_model
node_api_controller -->|"reads/writes"| node_course_model
node_api_controller -->|"reads/writes"| node_group_model
node_api_controller -->|"reads/writes"| node_assignment_model
node_api_controller -->|"reads/writes"| node_peer_review_model
node_dashboard_controller -->|"reads"| node_score_model
node_score_job -->|"updates"| node_score_model
node_score_job -->|"ingests"| node_github_api
node_api_controller -->|"persists"| node_mysql
node_score_model -->|"stored in"| node_mysql
node_node_service -->|"sends"| node_email_provider
node_email_controller -.->|"delegates"| node_node_service
node_api_controller -->|"fetches"| node_github_api

click node_frontend_app "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/index.html"
click node_frontend_services "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/services/api.js"
click node_frontend_layouts "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/layouts/MainLayout.js"
click node_frontend_components "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/components/common/Card.js"
click node_frontend_state "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/store/state.js"
click node_frontend_utils "https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/utils/pdfGenerator.js"
click node_routes_api "https://github.com/humayranuha/group_sync/blob/main/code/routes/api.php"
click node_routes_web "https://github.com/humayranuha/group_sync/blob/main/code/routes/web.php"
click node_api_controller "https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/ApiController.php"
click node_dashboard_controller "https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/DashboardController.php"
click node_email_controller "https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/NodeEmailController.php"
click node_score_job "https://github.com/humayranuha/group_sync/blob/main/code/app/Console/Commands/CalculateContributionScores.php"
click node_node_service "https://github.com/humayranuha/group_sync/blob/main/code/backend/server.js"
click node_user_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/User.php"
click node_course_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Course.php"
click node_group_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Group.php"
click node_assignment_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Assignment.php"
click node_peer_review_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/PeerReview.php"
click node_score_model "https://github.com/humayranuha/group_sync/blob/main/code/app/Models/ContributionScore.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_frontend_app,node_frontend_services,node_frontend_layouts,node_frontend_components,node_frontend_state,node_frontend_utils toneBlue
class node_routes_api,node_routes_web,node_api_controller,node_dashboard_controller,node_email_controller,node_score_job toneAmber
class node_user_model,node_course_model,node_group_model,node_assignment_model,node_peer_review_model,node_score_model toneMint
class node_node_service,node_github_api,node_email_provider,node_mysql toneRose
class node_browser toneNeutral
```

## Components

### Client UI

Role-based browser frontend and shared presentation components

- [Frontend App](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/index.html): SPA UI · Published JS frontend with role-based layouts and pages · `code/public/frontend/index.html`
- [API Services](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/services/api.js): frontend service layer · Auth, courses, groups, analytics, reports, GitHub, and AI calls · `code/public/frontend/services/api.js`
- [Role Layouts](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/layouts/MainLayout.js): navigation shell · Auth, main, professor, and student layout boundaries · `code/public/frontend/layouts/MainLayout.js`
- [UI Components](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/components/common/Card.js): shared widgets · Analytics, charts, common controls, and form components · `code/public/frontend/components/common/Card.js`
- [Client State](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/store/state.js): state store · Shared action and state management for the UI · `code/public/frontend/store/state.js`
- [Client Utils](https://github.com/humayranuha/group_sync/blob/main/code/public/frontend/utils/pdfGenerator.js): helpers · Formatting, validation, auth helpers, and PDF generation · `code/public/frontend/utils/pdfGenerator.js`

### Laravel Backend

Core application logic, API endpoints, and scheduled scoring

- [API Routes](https://github.com/humayranuha/group_sync/blob/main/code/routes/api.php): http routes · HTTP API surface for the frontend and integrations · `code/routes/api.php`
- [Web Routes](https://github.com/humayranuha/group_sync/blob/main/code/routes/web.php): http routes · Browser-facing and view-oriented routes · `code/routes/web.php`
- [API Controller](https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/ApiController.php): controller · Main domain endpoint controller · `code/app/Http/Controllers/ApiController.php`
- [Dashboard Controller](https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/DashboardController.php): controller · Dashboard and reporting views/data · `code/app/Http/Controllers/DashboardController.php`
- [Email Controller](https://github.com/humayranuha/group_sync/blob/main/code/app/Http/Controllers/NodeEmailController.php): integration controller · Node-backed email-related operations · `code/app/Http/Controllers/NodeEmailController.php`
- [Score Job](https://github.com/humayranuha/group_sync/blob/main/code/app/Console/Commands/CalculateContributionScores.php): artisan command · Periodic weighted contribution recalculation · `code/app/Console/Commands/CalculateContributionScores.php`

### Data Model

Primary persistent domain objects and stores

- [Users](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/User.php): domain model · Accounts, roles, GitHub fields, and student identity · `code/app/Models/User.php`
- [Courses](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Course.php): domain model · Course ownership and enrollment container · `code/app/Models/Course.php`
- [Groups](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Group.php): domain model · Student teams and membership boundary · `code/app/Models/Group.php`
- [Assignments](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/Assignment.php): domain model · Course tasks and evaluation targets · `code/app/Models/Assignment.php`
- [Peer Reviews](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/PeerReview.php): domain model · Student feedback and review records · `code/app/Models/PeerReview.php`
- [Contribution Scores](https://github.com/humayranuha/group_sync/blob/main/code/app/Models/ContributionScore.php): analytics model · Aggregated weighted contribution results · `code/app/Models/ContributionScore.php`

### External Services

Third-party and auxiliary runtime integrations

- [Node Service](https://github.com/humayranuha/group_sync/blob/main/code/backend/server.js): aux service · Secondary Express service for specialized backend work · `code/backend/server.js`
- **GitHub**: external api · Repository activity source for scoring
- **Email**: external service · Outbound notification and messaging channel
- **MySQL**: database · Primary relational persistence layer

### Other components

- **Browser**: client runtime · Students, professors, admins, and public users

## Connections

- Browser → Frontend App: uses · Users interact with the published frontend
- Frontend App → Role Layouts: navigates · Role-specific shells shape the user experience
- Frontend App → UI Components: renders · Pages compose shared UI widgets and charts
- Frontend App → API Services: calls · UI actions are translated into API and integration requests
- Frontend App → Client State: shares state · Client views coordinate via shared store
- Frontend App → Client Utils: uses · Formatting, validation, auth, and PDF helpers support the UI
- API Services → API Routes: requests · Frontend API layer targets Laravel endpoints
- Frontend App → Web Routes: loads views · Public and browser routes serve site pages
- API Routes → API Controller: dispatches · API routes are handled by the domain controller
- Web Routes → Dashboard Controller: dispatches · Web routes feed dashboards and page data
- API Controller → Users: reads/writes · Authentication and role-aware account logic
- API Controller → Courses: reads/writes · Course and enrollment management
- API Controller → Groups: reads/writes · Group creation, membership, and invitations
- API Controller → Assignments: reads/writes · Assignment setup and evaluation data
- API Controller → Peer Reviews: reads/writes · Peer review capture and aggregation
- Dashboard Controller → Contribution Scores: reads · Dashboards consume contribution analytics
- Score Job → Contribution Scores: updates · Scheduled job recalculates weighted scores
- Score Job → GitHub: ingests · GitHub activity contributes to scoring
- API Controller → MySQL: persists · Core domain state is stored in the database
- Contribution Scores → MySQL: stored in · Contribution results are persisted relationally
- Node Service → Email: sends · Auxiliary service supports email delivery
- Email Controller → Node Service: delegates · Laravel bridges to the Node mail service
- API Controller → GitHub: fetches · Repository linkage and activity tracking