# samiksha267/automated-lab-allocation-system architecture

> Architecture diagram of the GitHub repository samiksha267/automated-lab-allocation-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samiksha267/automated-lab-allocation-system
- Repository: https://github.com/samiksha267/automated-lab-allocation-system

## Overview

This is a React/Spring Boot college lab-allocation system backed by PostgreSQL. Users work through role-specific interfaces to maintain academic, faculty, subject, and lab data; schedules are generated against hard constraints, scored, explained, versioned, and exposed as timetables. Other documented capabilities include PDF timetable import, CR extra-lab booking, audit history, and analytics. The README supports the overall REST/database architecture; source excerpts establish routing, audit persistence, lab mutations, and recommendation internals. Several domain links are documented only at product level or were not sampled, so those edges are marked unverified.

Main entry points: [`frontend/src/api`](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/frontend/src/api) (REST clients), [`backend/src/main/java/com/college/laballocation/scheduling/generation/CandidateGenerator.java`](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/generation/CandidateGenerator.java) (Candidate generation), [`backend/src/main/java/com/college/laballocation/scheduling/TimetableController.java`](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/TimetableController.java) (Published timetable), [`backend/src/main/java/com/college/laballocation/lab/LabService.java`](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/lab/LabService.java) (Lab capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_routes["Role-based routes<br/>[AppRoutes.tsx]"]
  node_roleui["Role workflows"]
  node_api["REST clients"]
end

subgraph group_operations["Academic operations"]
  node_academic["Academic structure"]
  node_faculty["Faculty availability"]
  node_subjects["Subject requirements"]
  node_labs["Lab capabilities<br/>[LabService.java]"]
  node_pdfimport["Timetable import"]
  node_extra["Extra-lab booking"]
end

subgraph group_engine["Scheduling engine"]
  node_generation["Candidate generation"]
  node_constraints["Hard constraints"]
  node_scoring["Candidate scoring<br/>[ScoringEngine.java]"]
  node_explanation["Recommendations"]
  node_versions["Schedule versions"]
  node_timetable["Published timetable"]
end

subgraph group_insight["Operations insight"]
  node_analytics["Scheduling analytics"]
  node_audit["Audit history"]
end

subgraph group_platform["Backend platform"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_db[("PostgreSQL")]
end

node_staff(("College users"))

node_staff -->|"uses"| node_routes
node_routes -->|"routes to"| node_roleui
node_roleui -.->|"requests data"| node_api
node_api -->|"REST/JSON"| node_auth
node_auth -.->|"reads accounts"| node_db
node_api -->|"REST/JSON"| node_academic
node_api -->|"REST/JSON"| node_faculty
node_api -->|"REST/JSON"| node_subjects
node_api -->|"REST/JSON"| node_labs
node_api -->|"REST/JSON"| node_pdfimport
node_api -->|"REST/JSON"| node_extra
node_api -->|"REST/JSON"| node_timetable
node_generation -.->|"evaluates candidates"| node_constraints
node_generation -.->|"scores candidates"| node_scoring
node_explanation -->|"uses results"| node_generation
node_explanation -->|"uses scores"| node_scoring
node_timetable -.->|"schedules"| node_generation
node_versions -.->|"publishes versions"| node_timetable
node_pdfimport -.->|"imports schedule data"| node_timetable
node_extra -.->|"records actions"| node_audit
node_analytics -.->|"queries metrics"| node_db
node_audit -->|"persists events"| node_db
node_labs -->|"records mutations"| node_audit
node_academic -.->|"stores records"| node_db
node_faculty -.->|"stores availability"| node_db
node_subjects -.->|"stores requirements"| node_db
node_labs -.->|"stores lab data"| node_db
node_generation -.->|"loads scheduling data"| node_db
node_versions -.->|"stores versions"| node_db

click node_routes "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_roleui "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/frontend/src/features"
click node_api "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/frontend/src/api"
click node_academic "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/academic"
click node_faculty "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/faculty"
click node_subjects "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/subject"
click node_labs "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/lab/LabService.java"
click node_pdfimport "https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/timetableimport"
click node_extra "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/extra/ExtraLabService.java"
click node_generation "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/generation/CandidateGenerator.java"
click node_constraints "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/constraint/ConstraintEngine.java"
click node_scoring "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/scoring/ScoringEngine.java"
click node_explanation "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/explanation/ExplainableAllocationService.java"
click node_versions "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/ScheduleVersionService.java"
click node_timetable "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/TimetableController.java"
click node_analytics "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/analytics/AnalyticsService.java"
click node_audit "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/audit/AuditLogService.java"
click node_auth "https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/auth/AuthService.java"

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_routes,node_roleui,node_api,node_staff toneBlue
class node_academic,node_faculty,node_subjects,node_labs,node_pdfimport,node_extra toneAmber
class node_generation,node_constraints,node_scoring,node_explanation,node_versions,node_timetable toneMint
class node_analytics,node_audit toneRose
class node_auth,node_db toneIndigo
```

## Components

### Web application

- [Role-based routes](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`
- [Role workflows](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/frontend/src/features): `frontend/src/features`
- [REST clients](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/frontend/src/api): `frontend/src/api`

### Academic operations

- [Academic structure](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/academic): `backend/src/main/java/com/college/laballocation/academic`
- [Faculty availability](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/faculty): `backend/src/main/java/com/college/laballocation/faculty`
- [Subject requirements](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/subject): `backend/src/main/java/com/college/laballocation/subject`
- [Lab capabilities](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/lab/LabService.java): `backend/src/main/java/com/college/laballocation/lab/LabService.java`
- [Timetable import](https://github.com/samiksha267/automated-lab-allocation-system/tree/main/backend/src/main/java/com/college/laballocation/timetableimport): `backend/src/main/java/com/college/laballocation/timetableimport`
- [Extra-lab booking](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/extra/ExtraLabService.java): `backend/src/main/java/com/college/laballocation/scheduling/extra/ExtraLabService.java`

### Scheduling engine

- [Candidate generation](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/generation/CandidateGenerator.java): `backend/src/main/java/com/college/laballocation/scheduling/generation/CandidateGenerator.java`
- [Hard constraints](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/constraint/ConstraintEngine.java): `backend/src/main/java/com/college/laballocation/scheduling/constraint/ConstraintEngine.java`
- [Candidate scoring](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/scoring/ScoringEngine.java): `backend/src/main/java/com/college/laballocation/scheduling/scoring/ScoringEngine.java`
- [Recommendations](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/explanation/ExplainableAllocationService.java): `backend/src/main/java/com/college/laballocation/scheduling/explanation/ExplainableAllocationService.java`
- [Schedule versions](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/ScheduleVersionService.java): `backend/src/main/java/com/college/laballocation/scheduling/ScheduleVersionService.java`
- [Published timetable](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/scheduling/TimetableController.java): `backend/src/main/java/com/college/laballocation/scheduling/TimetableController.java`

### Operations insight

- [Scheduling analytics](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/analytics/AnalyticsService.java): `backend/src/main/java/com/college/laballocation/analytics/AnalyticsService.java`
- [Audit history](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/audit/AuditLogService.java): `backend/src/main/java/com/college/laballocation/audit/AuditLogService.java`

### Backend platform

- [Authentication](https://github.com/samiksha267/automated-lab-allocation-system/blob/main/backend/src/main/java/com/college/laballocation/auth/AuthService.java): `backend/src/main/java/com/college/laballocation/auth/AuthService.java`
- **PostgreSQL**

### Other components

- **College users**

## Connections

- College users → Role-based routes: uses (evidence: `frontend/src/routes/AppRoutes.tsx`)
- Role-based routes → Role workflows: routes to (evidence: `frontend/src/routes/AppRoutes.tsx`)
- Role workflows → REST clients: requests data (evidence: `frontend/src/features/auth/RequireRouteRole.tsx`)
- REST clients → Authentication: REST/JSON (evidence: `README.md`)
- Authentication → PostgreSQL: reads accounts
- REST clients → Academic structure: REST/JSON (evidence: `README.md`)
- REST clients → Faculty availability: REST/JSON (evidence: `README.md`)
- REST clients → Subject requirements: REST/JSON (evidence: `README.md`)
- REST clients → Lab capabilities: REST/JSON (evidence: `README.md`)
- REST clients → Timetable import: REST/JSON (evidence: `README.md`)
- REST clients → Extra-lab booking: REST/JSON (evidence: `README.md`)
- REST clients → Published timetable: REST/JSON (evidence: `README.md`)
- Candidate generation → Hard constraints: evaluates candidates
- Candidate generation → Candidate scoring: scores candidates
- Recommendations → Candidate generation: uses results (evidence: `backend/src/main/java/com/college/laballocation/scheduling/explanation/ExplainableAllocationService.java`)
- Recommendations → Candidate scoring: uses scores (evidence: `backend/src/main/java/com/college/laballocation/scheduling/explanation/ExplainableAllocationService.java`)
- Published timetable → Candidate generation: schedules
- Schedule versions → Published timetable: publishes versions
- Timetable import → Published timetable: imports schedule data
- Extra-lab booking → Audit history: records actions (evidence: `backend/src/main/java/com/college/laballocation/scheduling/extra/ExtraLabService.java`)
- Scheduling analytics → PostgreSQL: queries metrics
- Audit history → PostgreSQL: persists events (evidence: `backend/src/main/java/com/college/laballocation/audit/AuditLogService.java`)
- Lab capabilities → Audit history: records mutations (evidence: `backend/src/main/java/com/college/laballocation/lab/LabService.java`)
- Academic structure → PostgreSQL: stores records
- Faculty availability → PostgreSQL: stores availability
- Subject requirements → PostgreSQL: stores requirements
- Lab capabilities → PostgreSQL: stores lab data
- Candidate generation → PostgreSQL: loads scheduling data
- Schedule versions → PostgreSQL: stores versions
