From 3e3c875e0058bafaf0912c67f5e3293760a8ce56 Mon Sep 17 00:00:00 2001 From: Divyansh Date: Wed, 10 Jun 2026 15:44:49 +0530 Subject: [PATCH 1/7] Fix #86: assign names to all users --- app/src/pages/auth/CentreHeadSignup.tsx | 13 +++++++++++++ app/src/pages/auth/WardenSignup.tsx | 13 +++++++++++++ handlers/centrehead_auth.go | 1 + handlers/warden_auth.go | 1 + models/centrehead_auth.go | 2 ++ models/warden_auth.go | 2 ++ 6 files changed, 32 insertions(+) diff --git a/app/src/pages/auth/CentreHeadSignup.tsx b/app/src/pages/auth/CentreHeadSignup.tsx index 6630de3..e8b8737 100644 --- a/app/src/pages/auth/CentreHeadSignup.tsx +++ b/app/src/pages/auth/CentreHeadSignup.tsx @@ -6,6 +6,7 @@ import { BUILDINGS } from '../../constants/models'; export function CentreHeadSignup() { const [formData, setFormData] = useState({ + name: '', email: '', password: '', phone_number: '', @@ -97,6 +98,18 @@ export function CentreHeadSignup() {

Account Details

+
+ + +

Account Details

+
+ + +
Date: Wed, 10 Jun 2026 15:53:09 +0530 Subject: [PATCH 2/7] Fix #86 tests: Add name field to mock payloads --- test/centrehead_auth_test.go | 1 + test/warden_auth_test.go | 1 + 2 files changed, 2 insertions(+) diff --git a/test/centrehead_auth_test.go b/test/centrehead_auth_test.go index 97f431d..4bb9c4a 100644 --- a/test/centrehead_auth_test.go +++ b/test/centrehead_auth_test.go @@ -24,6 +24,7 @@ func TestCentreheadSignup_AlreadyRegistered(t *testing.T) { e := newAuthRouter(db, noAuth()) body := map[string]any{ + "name": "Duplicate Head", "email": "ch.dup@iit.ac.in", "password": "whatever", "building": string(models.LHC), diff --git a/test/warden_auth_test.go b/test/warden_auth_test.go index e3e119f..ee6ea8c 100644 --- a/test/warden_auth_test.go +++ b/test/warden_auth_test.go @@ -24,6 +24,7 @@ func TestWardenSignup_AlreadyRegistered(t *testing.T) { e := newAuthRouter(db, noAuth()) body := map[string]any{ + "name": "Duplicate Warden", "email": "war.dup@iit.ac.in", "password": "whatever", "hostel": string(models.KBH), From 7edf91e7e69ab0a9bc6aee214003c643c62bde14 Mon Sep 17 00:00:00 2001 From: Divyansh Date: Mon, 22 Jun 2026 14:18:27 +0530 Subject: [PATCH 3/7] feat: allow for editing and deleting admin comments (fixes #41) --- handlers/admin_comment.go | 120 ++++++++++++++++++++++++++++++++++++++ routes/admin.go | 2 + 2 files changed, 122 insertions(+) diff --git a/handlers/admin_comment.go b/handlers/admin_comment.go index 7c2026a..5810a15 100644 --- a/handlers/admin_comment.go +++ b/handlers/admin_comment.go @@ -103,3 +103,123 @@ func (h *AdminHandler) AdminPostComment(c *gin.Context) { c.JSON(201, gin.H{"success": "comment posted!"}) } + +// AdminEditComment allows an admin to edit their own comment. +func (h *AdminHandler) AdminEditComment(c *gin.Context) { + // verify the admin + emailID, exists := c.Get(middleware.EmailKey) + if !exists { + c.JSON(401, gin.H{"error": "permission denied"}) + return + } + + var inputs CommentType + if err := c.ShouldBindJSON(&inputs); err != nil { + c.JSON(400, gin.H{"error": "invalid request body"}) + return + } + + postType := c.Param("type") + postIDString := c.Param("id") + postID, err := strconv.ParseUint(postIDString, 10, 64) + if err != nil { + c.JSON(400, gin.H{"error": "invalid post id"}) + return + } + + commentIDString := c.Param("comment_id") + commentID, err := strconv.ParseUint(commentIDString, 10, 64) + if err != nil { + c.JSON(400, gin.H{"error": "invalid comment id"}) + return + } + + var comment models.Comment + result := h.DB.Where("id = ?", commentID).Take(&comment) + if result.Error != nil { + if errors.Is(result.Error, gorm.ErrRecordNotFound) { + c.JSON(404, gin.H{"error": "comment not found"}) + return + } + c.JSON(500, gin.H{"error": "internal server error"}) + return + } + + if comment.CommentableType != postType || comment.CommentableID != uint(postID) { + c.JSON(400, gin.H{"error": "comment does not belong to this post"}) + return + } + + // Verify that the comment belongs to this admin + if comment.Email != emailID { + c.JSON(403, gin.H{"error": "you are not authorized to edit this comment"}) + return + } + + // Update the comment + comment.Content = inputs.Content + comment.UpdatedAt = time.Now() + + result = h.DB.Save(&comment) + if result.Error != nil { + c.JSON(500, gin.H{"error": "failed to update comment"}) + return + } + + c.JSON(200, gin.H{"success": "comment updated!"}) +} + +// AdminDeleteComment allows an admin to delete their own comment. +func (h *AdminHandler) AdminDeleteComment(c *gin.Context) { + // verify the admin + emailID, exists := c.Get(middleware.EmailKey) + if !exists { + c.JSON(401, gin.H{"error": "permission denied"}) + return + } + + postType := c.Param("type") + postIDString := c.Param("id") + postID, err := strconv.ParseUint(postIDString, 10, 64) + if err != nil { + c.JSON(400, gin.H{"error": "invalid post id"}) + return + } + + commentIDString := c.Param("comment_id") + commentID, err := strconv.ParseUint(commentIDString, 10, 64) + if err != nil { + c.JSON(400, gin.H{"error": "invalid comment id"}) + return + } + + var comment models.Comment + result := h.DB.Where("id = ?", commentID).Take(&comment) + if result.Error != nil { + if errors.Is(result.Error, gorm.ErrRecordNotFound) { + c.JSON(404, gin.H{"error": "comment not found"}) + return + } + c.JSON(500, gin.H{"error": "internal server error"}) + return + } + + if comment.CommentableType != postType || comment.CommentableID != uint(postID) { + c.JSON(400, gin.H{"error": "comment does not belong to this post"}) + return + } + + // Verify that the comment belongs to this admin + if comment.Email != emailID { + c.JSON(403, gin.H{"error": "you are not authorized to delete this comment"}) + return + } + + result = h.DB.Delete(&comment) + if result.Error != nil { + c.JSON(500, gin.H{"error": "failed to delete comment"}) + return + } + + c.JSON(200, gin.H{"success": "comment deleted!"}) +} diff --git a/routes/admin.go b/routes/admin.go index 13678f1..3d88c1f 100644 --- a/routes/admin.go +++ b/routes/admin.go @@ -11,6 +11,8 @@ func AdminRoutes (e *gin.Engine, h *handlers.AdminHandler) { e.POST("/api/auth/admin/login", h.AdminLogin) e.POST("/api/admin/comment/:type/:id", middleware.IsAuthenticated(), h.AdminPostComment) + e.PATCH("/api/admin/comment/:type/:id/:comment_id", middleware.IsAuthenticated(), h.AdminEditComment) + e.DELETE("/api/admin/comment/:type/:id/:comment_id", middleware.IsAuthenticated(), h.AdminDeleteComment) // keep separate apis for updating status stage := e.Group("/api/admin") From 806f966348ae91dbd4e64b6de19963f99a4fbb39 Mon Sep 17 00:00:00 2001 From: Divyansh Date: Mon, 22 Jun 2026 14:22:06 +0530 Subject: [PATCH 4/7] feat: add AdminGetComments endpoint to fetch admin's own comments --- handlers/admin_comment.go | 21 +++++++++++++++++++++ routes/admin.go | 1 + 2 files changed, 22 insertions(+) diff --git a/handlers/admin_comment.go b/handlers/admin_comment.go index 5810a15..170079f 100644 --- a/handlers/admin_comment.go +++ b/handlers/admin_comment.go @@ -24,6 +24,27 @@ type CommentType struct { // AdminGetComments ///////////////////////////////////////////////////////////////////// +// AdminGetComments fetches all comments made by the logged-in admin. +func (h *AdminHandler) AdminGetComments(c *gin.Context) { + emailID, exists := c.Get(middleware.EmailKey) + if !exists { + c.JSON(401, gin.H{"error": "permission denied"}) + return + } + + var comments []models.Comment + result := h.DB.Where("email = ?", emailID).Find(&comments) + if result.Error != nil { + c.JSON(500, gin.H{"error": "failed to fetch comments"}) + return + } + + c.JSON(200, gin.H{ + "success": "comments fetched", + "comments": comments, + }) +} + // AdminPost comment allow any admin comment on any type of post. // Common for all type of admins and posts. diff --git a/routes/admin.go b/routes/admin.go index 3d88c1f..3981ed6 100644 --- a/routes/admin.go +++ b/routes/admin.go @@ -10,6 +10,7 @@ func AdminRoutes (e *gin.Engine, h *handlers.AdminHandler) { // e.POST("/api/auth/admin/signup", h.AdminSignup) // not to be used as an public API e.POST("/api/auth/admin/login", h.AdminLogin) + e.GET("/api/admin/comments", middleware.IsAuthenticated(), h.AdminGetComments) e.POST("/api/admin/comment/:type/:id", middleware.IsAuthenticated(), h.AdminPostComment) e.PATCH("/api/admin/comment/:type/:id/:comment_id", middleware.IsAuthenticated(), h.AdminEditComment) e.DELETE("/api/admin/comment/:type/:id/:comment_id", middleware.IsAuthenticated(), h.AdminDeleteComment) From 58b92784958296f37db7b00ce4a08b6dafb6c4fa Mon Sep 17 00:00:00 2001 From: Divyansh Date: Mon, 22 Jun 2026 14:30:21 +0530 Subject: [PATCH 5/7] docs: add wiki pages (Home, Setup, Architecture, API Reference, Contributing) --- docs/API-Reference.md | 86 ++++++++++++++++++++++++++++++++++ docs/Architecture-and-Flows.md | 52 ++++++++++++++++++++ docs/Contributing.md | 41 ++++++++++++++++ docs/Home.md | 20 ++++++++ docs/Local-Setup.md | 61 ++++++++++++++++++++++++ 5 files changed, 260 insertions(+) create mode 100644 docs/API-Reference.md create mode 100644 docs/Architecture-and-Flows.md create mode 100644 docs/Contributing.md create mode 100644 docs/Home.md create mode 100644 docs/Local-Setup.md diff --git a/docs/API-Reference.md b/docs/API-Reference.md new file mode 100644 index 0000000..509769c --- /dev/null +++ b/docs/API-Reference.md @@ -0,0 +1,86 @@ +# API Reference + +This document maps all the API endpoints available in the CMS Web backend. Most endpoints require authentication via token cookies checked by the `IsAuthenticated` middleware. + +--- + +## 1. Authentication Routes + +### Faculty Auth +* `POST /api/auth/faculty/signup` - Register a new faculty account +* `POST /api/auth/faculty/login` - Login to a faculty account +* `POST /api/auth/faculty/forget-password` - Request a password reset link +* `PATCH /api/auth/faculty/reset-password` - Complete password reset using token + +### Warden Auth +* `POST /api/auth/warden/signup` - Register a new warden account +* `POST /api/auth/warden/login` - Login to a warden account +* `POST /api/auth/warden/forget-password` - Request a password reset link +* `PATCH /api/auth/warden/reset-password` - Complete password reset using token + +### Centrehead Auth +* `POST /api/auth/centrehead/signup` - Register a new centrehead account +* `POST /api/auth/centrehead/login` - Login to a centrehead account +* `POST /api/auth/centrehead/forget-password` - Request a password reset link +* `PATCH /api/auth/centrehead/reset-password` - Complete password reset using token + +### Admin Auth +* `POST /api/auth/admin/login` - Login to an admin account (XEN, AE, JE) + +### General Auth +* `POST /api/auth/logout` - Clear authentication cookies +* `GET /api/auth/verify` - Verify an account via email link +* `GET /api/profile` - Fetch the profile details of the current logged-in user + +--- + +## 2. Complaint (Post) Routes + +Protected by `IsAuthenticated` middleware. + +* `POST /api/post/faculty` - Submit a new faculty post +* `POST /api/post/warden` - Submit a new warden post +* `POST /api/post/centrehead` - Submit a new centrehead post + +* `PATCH /api/post/faculty/edit/:post_id` - Edit a faculty post (valid for 30 mins post-creation) +* `PATCH /api/post/warden/edit/:post_id` - Edit a warden post (valid for 30 mins post-creation) +* `PATCH /api/post/centrehead/edit/:post_id` - Edit a centrehead post (valid for 30 mins post-creation) + +* `DELETE /api/post/faculty/delete/:post_id` - Delete a faculty post (valid for 30 mins post-creation) +* `DELETE /api/post/warden/delete/:post_id` - Delete a warden post (valid for 30 mins post-creation) +* `DELETE /api/post/centrehead/delete/:post_id` - Delete a centrehead post (valid for 30 mins post-creation) + +* `GET /api/post/faculty` - Retrieve posts submitted by the logged-in faculty +* `GET /api/post/warden` - Retrieve posts submitted by the logged-in warden +* `GET /api/post/centrehead` - Retrieve posts submitted by the logged-in centrehead + +--- + +## 3. Comments Routes + +* `POST /api/post/faculty/comment/:post_id` - Comment on a faculty post (as post author) +* `POST /api/post/warden/comment/:post_id` - Comment on a warden post (as post author) +* `POST /api/post/centrehead/comment/:post_id` - Comment on a centrehead post (as post author) + +--- + +## 4. Admin Operations Routes + +Admins can perform operations across any user post types and manage comments/statuses. + +### Comments Management +* `GET /api/admin/comments` - Fetch all comments created by the logged-in admin +* `POST /api/admin/comment/:type/:id` - Post an admin comment on a specific post (`type` can be `faculty_posts`, `warden_posts`, `centrehead_posts`) +* `PATCH /api/admin/comment/:type/:id/:comment_id` - Edit an admin's own comment +* `DELETE /api/admin/comment/:type/:id/:comment_id` - Delete an admin's own comment + +### Status Management +* `PATCH /api/admin/faculty_posts/status/:post_id` - Update status of a faculty post +* `PATCH /api/admin/warden_posts/status/:post_id` - Update status of a warden post +* `PATCH /api/admin/centrehead_posts/status/:post_id` - Update status of a centrehead post + +### Post Queries +* `GET /api/admin/xen/posts` - Fetch posts available to XEN +* `GET /api/admin/ae/posts` - Fetch posts available to AE +* `GET /api/admin/je/posts` - Fetch posts assigned to JE +* `GET /api/admin/posts/:role/:post_id` - Fetch details of any post by role and ID diff --git a/docs/Architecture-and-Flows.md b/docs/Architecture-and-Flows.md new file mode 100644 index 0000000..2625f5f --- /dev/null +++ b/docs/Architecture-and-Flows.md @@ -0,0 +1,52 @@ +# Architecture & Flows + +CMS Web relies on a role-based workflow to process maintenance complaints efficiently. + +## 1. Role-Based Authorization + +The system classifies users into distinct roles, each having specific privileges: +* **Faculty**: Submits departmental or residential complaints. Can comment, edit, or delete posts within a 30-minute window. +* **Warden**: Submits hostel-related complaints. Can comment, edit, or delete posts within a 30-minute window. +* **Centrehead**: Submits administrative/building-related complaints. Can comment, edit, or delete posts within a 30-minute window. +* **Admin (XEN, AE, JE)**: + * **XEN (Executive Engineer)**: Oversees all pending posts, assigns Junior Engineers (JE), and manages post statuses. + * **AE (Assistant Engineer)**: Reviews posts pending AE review and manages them. + * **JE (Junior Engineer)**: Resolves assignments directly or reports progress. + +*Diagram location:* `/public/img/cms6.png` + +--- + +## 2. Authentication Flow + +Authentication is session or token-based, verifying credentials (login) and checking positions/roles on protected routes via custom Gin middleware. + +*Diagram location:* `/public/img/cms1.png` + +--- + +## 3. Complaint Lifecycle Flow + +The typical flow of a complaint from submission to closure: +1. **Creation**: Submissions by Faculty, Warden, or Centrehead default to the `Pending_XEN` status. +2. **Review/Assignment**: The XEN reviews and delegates it to a Junior Engineer (`Pending_JE`). +3. **Execution**: The JE performs the work and updates the status to `Resolved_JE`. +4. **Resolution**: The complaint progresses through administrative checks (AE / XEN) until it reaches `Resolved` or `Closed`. + +*Diagram location:* `/public/img/cms2.png` + +--- + +## 4. Request Status Matrix (XEN, JE) + +A quick matrix showing how request statuses transition between the Executive Engineer (XEN) and the Junior Engineer (JE): + +*Diagram location:* `/public/img/cms3.png` + +--- + +## 5. Request Status (AE) + +How Assistant Engineers (AE) intervene in the verification process for specific complaints: + +*Diagram location:* `/public/img/cms4.png` diff --git a/docs/Contributing.md b/docs/Contributing.md new file mode 100644 index 0000000..8dc243a --- /dev/null +++ b/docs/Contributing.md @@ -0,0 +1,41 @@ +# Contributing Guide + +Thank you for contributing to CMS Web! To maintain code quality and ensure a smooth development process, please adhere to the following guidelines. + +--- + +## 1. Development Workflow + +1. **Create a Branch**: Create a descriptive feature branch from `main`: + ```bash + git checkout -b feat/your-feature-name + ``` +2. **Implement Changes**: Ensure your changes are modular and contain appropriate comments. Avoid unrelated refactorings. +3. **Run Tests**: Always run backend tests locally to verify no regressions were introduced: + ```bash + go test -v ./test/... + ``` +4. **Commit & Push**: Commit with concise messages conforming to conventional commits (e.g. `feat: add ...`, `fix: resolve ...`): + ```bash + git add . + git commit -m "feat: add user profile page" + git push origin feat/your-feature-name + ``` +5. **Pull Request**: Open a pull request against the `main` branch. Provide a comprehensive summary of your changes. + +--- + +## 2. Code Conventions + +### Backend (Go) +* **GORM Models**: When creating or modifying database schemas, verify relationships and validation tags (e.g., `binding:"required"`, `gorm:"not null"`). +* **Endpoints**: Add routes to their designated category in the `routes/` package. +* **Error Handling**: Follow idiomatic Go patterns. Return clear JSON error payloads with relevant HTTP statuses: + * `400 Bad Request` for invalid input parameters/schemas. + * `401 Unauthorized` / `403 Forbidden` for failed authentication/authorization checks. + * `404 Not Found` when GORM queries return `gorm.ErrRecordNotFound`. + * `500 Internal Server Error` for database failures. + +### Frontend (React + TS) +* **TypeScript**: Define explicit types/interfaces for state, props, and API response schemas. Avoid using `any` whenever possible. +* **Styling**: Maintain vanilla CSS conventions and structure styles clearly within component directories. diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..37f19f0 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,20 @@ +# Welcome to the CMS Web Wiki + +**CMS Web** is the official web interface of the Estate Office of NIT Hamirpur designed to streamline and manage maintenance complaints across the campus. It handles both **civil** and **electrical** complaints for both **official/departmental** buildings and **residential** quarters. + +## Project Structure + +Here is a quick overview of the key directories in this project: + +- **`/app`**: The frontend application built using **Vite**, **React**, and **TypeScript**. +- **`/handlers`**: Go backend controller logic handling authentication, posts (complaints), and comments. +- **`/models`**: Gorm database models representing users (Faculty, Warden, Centrehead, Admin), posts, and comments. +- **`/routes`**: API routing configurations for both user actions and administrative control. +- **`/middleware`**: Backend middleware including authentication and permissions checking. +- **`/test`**: Go backend test suite verifying auth flows, complaint management, and administrative actions. + +## Quick Links +- [[Local Setup|Local-Setup]] +- [[Architecture & Flows|Architecture-and-Flows]] +- [[API Reference|API-Reference]] +- [[Contributing|Contributing]] diff --git a/docs/Local-Setup.md b/docs/Local-Setup.md new file mode 100644 index 0000000..9de4122 --- /dev/null +++ b/docs/Local-Setup.md @@ -0,0 +1,61 @@ +# Local Setup + +This guide will help you get CMS Web running locally on your development machine. The project is split into a Go backend and a React + TypeScript frontend. + +## Prerequisites + +Ensure you have the following installed: +- [Go](https://go.dev/dl/) (version 1.20+) +- [Node.js](https://nodejs.org/en) (v18+) and npm +- A relational database (SQLite by default or PostgreSQL/MySQL depending on configuration) + +--- + +## 1. Backend Setup + +The backend is built in Go using the **Gin** framework and **GORM**. + +1. Navigate to the root directory of the project. +2. Create your `.env` configuration file from the example: + ```bash + cp .env.example .env + ``` + Configure your database credentials and secret keys inside `.env`. +3. Install the dependencies: + ```bash + go mod download + ``` +4. Run the backend server: + ```bash + go run main.go + ``` + The backend should now be running on its configured port (typically `:8080`). + +--- + +## 2. Frontend Setup + +The frontend is located in the `/app` folder. + +1. Navigate to the `/app` directory: + ```bash + cd app + ``` +2. Install dependencies: + ```bash + npm install + ``` +3. Run the Vite development server: + ```bash + npm run dev + ``` +4. Open the local address printed in the terminal (usually `http://localhost:5173`) in your browser. + +--- + +## 3. Running Tests + +To verify that everything is working as expected, run the Go test suite: +```bash +go test -v ./test/... +``` From b0b96903cef2ad1b96d1c52acf2866aabb43708f Mon Sep 17 00:00:00 2001 From: Divyansh Date: Mon, 22 Jun 2026 14:37:16 +0530 Subject: [PATCH 6/7] docs: use raw github urls to embed flowcharts in Architecture and Flows wiki --- docs/Architecture-and-Flows.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/Architecture-and-Flows.md b/docs/Architecture-and-Flows.md index 2625f5f..2139ab9 100644 --- a/docs/Architecture-and-Flows.md +++ b/docs/Architecture-and-Flows.md @@ -13,7 +13,7 @@ The system classifies users into distinct roles, each having specific privileges * **AE (Assistant Engineer)**: Reviews posts pending AE review and manages them. * **JE (Junior Engineer)**: Resolves assignments directly or reports progress. -*Diagram location:* `/public/img/cms6.png` +![Role-Based Authorization](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms6.png) --- @@ -21,7 +21,7 @@ The system classifies users into distinct roles, each having specific privileges Authentication is session or token-based, verifying credentials (login) and checking positions/roles on protected routes via custom Gin middleware. -*Diagram location:* `/public/img/cms1.png` +![Authentication Flow](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms1.png) --- @@ -33,7 +33,7 @@ The typical flow of a complaint from submission to closure: 3. **Execution**: The JE performs the work and updates the status to `Resolved_JE`. 4. **Resolution**: The complaint progresses through administrative checks (AE / XEN) until it reaches `Resolved` or `Closed`. -*Diagram location:* `/public/img/cms2.png` +![Complaint Lifecycle Flow](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms2.png) --- @@ -41,7 +41,7 @@ The typical flow of a complaint from submission to closure: A quick matrix showing how request statuses transition between the Executive Engineer (XEN) and the Junior Engineer (JE): -*Diagram location:* `/public/img/cms3.png` +![Request Status Matrix](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms3.png) --- @@ -49,4 +49,5 @@ A quick matrix showing how request statuses transition between the Executive Eng How Assistant Engineers (AE) intervene in the verification process for specific complaints: -*Diagram location:* `/public/img/cms4.png` +![Request Status AE](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms4.png) + From 8ecaf0f21edec56026c9e0562dd31bc466b35064 Mon Sep 17 00:00:00 2001 From: Divyansh Date: Mon, 22 Jun 2026 18:19:39 +0530 Subject: [PATCH 7/7] remove docs/ dir and fix frontend api paths --- app/src/pages/admin/AdminPostView.tsx | 2 +- docs/API-Reference.md | 86 --------------------------- docs/Architecture-and-Flows.md | 53 ----------------- docs/Contributing.md | 41 ------------- docs/Home.md | 20 ------- docs/Local-Setup.md | 61 ------------------- routes/admin.go | 6 +- 7 files changed, 4 insertions(+), 265 deletions(-) delete mode 100644 docs/API-Reference.md delete mode 100644 docs/Architecture-and-Flows.md delete mode 100644 docs/Contributing.md delete mode 100644 docs/Home.md delete mode 100644 docs/Local-Setup.md diff --git a/app/src/pages/admin/AdminPostView.tsx b/app/src/pages/admin/AdminPostView.tsx index bf24890..f01cb6a 100644 --- a/app/src/pages/admin/AdminPostView.tsx +++ b/app/src/pages/admin/AdminPostView.tsx @@ -138,7 +138,7 @@ const ROLE_TO_STATUS_API: Record = { // Maps URL role param → API segment for the comment endpoint const ROLE_TO_COMMENT_API: Record = { faculty: 'faculty_posts', - warden: 'wardens_posts', + warden: 'warden_posts', centrehead: 'centrehead_posts', }; diff --git a/docs/API-Reference.md b/docs/API-Reference.md deleted file mode 100644 index 509769c..0000000 --- a/docs/API-Reference.md +++ /dev/null @@ -1,86 +0,0 @@ -# API Reference - -This document maps all the API endpoints available in the CMS Web backend. Most endpoints require authentication via token cookies checked by the `IsAuthenticated` middleware. - ---- - -## 1. Authentication Routes - -### Faculty Auth -* `POST /api/auth/faculty/signup` - Register a new faculty account -* `POST /api/auth/faculty/login` - Login to a faculty account -* `POST /api/auth/faculty/forget-password` - Request a password reset link -* `PATCH /api/auth/faculty/reset-password` - Complete password reset using token - -### Warden Auth -* `POST /api/auth/warden/signup` - Register a new warden account -* `POST /api/auth/warden/login` - Login to a warden account -* `POST /api/auth/warden/forget-password` - Request a password reset link -* `PATCH /api/auth/warden/reset-password` - Complete password reset using token - -### Centrehead Auth -* `POST /api/auth/centrehead/signup` - Register a new centrehead account -* `POST /api/auth/centrehead/login` - Login to a centrehead account -* `POST /api/auth/centrehead/forget-password` - Request a password reset link -* `PATCH /api/auth/centrehead/reset-password` - Complete password reset using token - -### Admin Auth -* `POST /api/auth/admin/login` - Login to an admin account (XEN, AE, JE) - -### General Auth -* `POST /api/auth/logout` - Clear authentication cookies -* `GET /api/auth/verify` - Verify an account via email link -* `GET /api/profile` - Fetch the profile details of the current logged-in user - ---- - -## 2. Complaint (Post) Routes - -Protected by `IsAuthenticated` middleware. - -* `POST /api/post/faculty` - Submit a new faculty post -* `POST /api/post/warden` - Submit a new warden post -* `POST /api/post/centrehead` - Submit a new centrehead post - -* `PATCH /api/post/faculty/edit/:post_id` - Edit a faculty post (valid for 30 mins post-creation) -* `PATCH /api/post/warden/edit/:post_id` - Edit a warden post (valid for 30 mins post-creation) -* `PATCH /api/post/centrehead/edit/:post_id` - Edit a centrehead post (valid for 30 mins post-creation) - -* `DELETE /api/post/faculty/delete/:post_id` - Delete a faculty post (valid for 30 mins post-creation) -* `DELETE /api/post/warden/delete/:post_id` - Delete a warden post (valid for 30 mins post-creation) -* `DELETE /api/post/centrehead/delete/:post_id` - Delete a centrehead post (valid for 30 mins post-creation) - -* `GET /api/post/faculty` - Retrieve posts submitted by the logged-in faculty -* `GET /api/post/warden` - Retrieve posts submitted by the logged-in warden -* `GET /api/post/centrehead` - Retrieve posts submitted by the logged-in centrehead - ---- - -## 3. Comments Routes - -* `POST /api/post/faculty/comment/:post_id` - Comment on a faculty post (as post author) -* `POST /api/post/warden/comment/:post_id` - Comment on a warden post (as post author) -* `POST /api/post/centrehead/comment/:post_id` - Comment on a centrehead post (as post author) - ---- - -## 4. Admin Operations Routes - -Admins can perform operations across any user post types and manage comments/statuses. - -### Comments Management -* `GET /api/admin/comments` - Fetch all comments created by the logged-in admin -* `POST /api/admin/comment/:type/:id` - Post an admin comment on a specific post (`type` can be `faculty_posts`, `warden_posts`, `centrehead_posts`) -* `PATCH /api/admin/comment/:type/:id/:comment_id` - Edit an admin's own comment -* `DELETE /api/admin/comment/:type/:id/:comment_id` - Delete an admin's own comment - -### Status Management -* `PATCH /api/admin/faculty_posts/status/:post_id` - Update status of a faculty post -* `PATCH /api/admin/warden_posts/status/:post_id` - Update status of a warden post -* `PATCH /api/admin/centrehead_posts/status/:post_id` - Update status of a centrehead post - -### Post Queries -* `GET /api/admin/xen/posts` - Fetch posts available to XEN -* `GET /api/admin/ae/posts` - Fetch posts available to AE -* `GET /api/admin/je/posts` - Fetch posts assigned to JE -* `GET /api/admin/posts/:role/:post_id` - Fetch details of any post by role and ID diff --git a/docs/Architecture-and-Flows.md b/docs/Architecture-and-Flows.md deleted file mode 100644 index 2139ab9..0000000 --- a/docs/Architecture-and-Flows.md +++ /dev/null @@ -1,53 +0,0 @@ -# Architecture & Flows - -CMS Web relies on a role-based workflow to process maintenance complaints efficiently. - -## 1. Role-Based Authorization - -The system classifies users into distinct roles, each having specific privileges: -* **Faculty**: Submits departmental or residential complaints. Can comment, edit, or delete posts within a 30-minute window. -* **Warden**: Submits hostel-related complaints. Can comment, edit, or delete posts within a 30-minute window. -* **Centrehead**: Submits administrative/building-related complaints. Can comment, edit, or delete posts within a 30-minute window. -* **Admin (XEN, AE, JE)**: - * **XEN (Executive Engineer)**: Oversees all pending posts, assigns Junior Engineers (JE), and manages post statuses. - * **AE (Assistant Engineer)**: Reviews posts pending AE review and manages them. - * **JE (Junior Engineer)**: Resolves assignments directly or reports progress. - -![Role-Based Authorization](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms6.png) - ---- - -## 2. Authentication Flow - -Authentication is session or token-based, verifying credentials (login) and checking positions/roles on protected routes via custom Gin middleware. - -![Authentication Flow](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms1.png) - ---- - -## 3. Complaint Lifecycle Flow - -The typical flow of a complaint from submission to closure: -1. **Creation**: Submissions by Faculty, Warden, or Centrehead default to the `Pending_XEN` status. -2. **Review/Assignment**: The XEN reviews and delegates it to a Junior Engineer (`Pending_JE`). -3. **Execution**: The JE performs the work and updates the status to `Resolved_JE`. -4. **Resolution**: The complaint progresses through administrative checks (AE / XEN) until it reaches `Resolved` or `Closed`. - -![Complaint Lifecycle Flow](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms2.png) - ---- - -## 4. Request Status Matrix (XEN, JE) - -A quick matrix showing how request statuses transition between the Executive Engineer (XEN) and the Junior Engineer (JE): - -![Request Status Matrix](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms3.png) - ---- - -## 5. Request Status (AE) - -How Assistant Engineers (AE) intervene in the verification process for specific complaints: - -![Request Status AE](https://raw.githubusercontent.com/divyansh-v15-06/cms-webb/main/public/img/cms4.png) - diff --git a/docs/Contributing.md b/docs/Contributing.md deleted file mode 100644 index 8dc243a..0000000 --- a/docs/Contributing.md +++ /dev/null @@ -1,41 +0,0 @@ -# Contributing Guide - -Thank you for contributing to CMS Web! To maintain code quality and ensure a smooth development process, please adhere to the following guidelines. - ---- - -## 1. Development Workflow - -1. **Create a Branch**: Create a descriptive feature branch from `main`: - ```bash - git checkout -b feat/your-feature-name - ``` -2. **Implement Changes**: Ensure your changes are modular and contain appropriate comments. Avoid unrelated refactorings. -3. **Run Tests**: Always run backend tests locally to verify no regressions were introduced: - ```bash - go test -v ./test/... - ``` -4. **Commit & Push**: Commit with concise messages conforming to conventional commits (e.g. `feat: add ...`, `fix: resolve ...`): - ```bash - git add . - git commit -m "feat: add user profile page" - git push origin feat/your-feature-name - ``` -5. **Pull Request**: Open a pull request against the `main` branch. Provide a comprehensive summary of your changes. - ---- - -## 2. Code Conventions - -### Backend (Go) -* **GORM Models**: When creating or modifying database schemas, verify relationships and validation tags (e.g., `binding:"required"`, `gorm:"not null"`). -* **Endpoints**: Add routes to their designated category in the `routes/` package. -* **Error Handling**: Follow idiomatic Go patterns. Return clear JSON error payloads with relevant HTTP statuses: - * `400 Bad Request` for invalid input parameters/schemas. - * `401 Unauthorized` / `403 Forbidden` for failed authentication/authorization checks. - * `404 Not Found` when GORM queries return `gorm.ErrRecordNotFound`. - * `500 Internal Server Error` for database failures. - -### Frontend (React + TS) -* **TypeScript**: Define explicit types/interfaces for state, props, and API response schemas. Avoid using `any` whenever possible. -* **Styling**: Maintain vanilla CSS conventions and structure styles clearly within component directories. diff --git a/docs/Home.md b/docs/Home.md deleted file mode 100644 index 37f19f0..0000000 --- a/docs/Home.md +++ /dev/null @@ -1,20 +0,0 @@ -# Welcome to the CMS Web Wiki - -**CMS Web** is the official web interface of the Estate Office of NIT Hamirpur designed to streamline and manage maintenance complaints across the campus. It handles both **civil** and **electrical** complaints for both **official/departmental** buildings and **residential** quarters. - -## Project Structure - -Here is a quick overview of the key directories in this project: - -- **`/app`**: The frontend application built using **Vite**, **React**, and **TypeScript**. -- **`/handlers`**: Go backend controller logic handling authentication, posts (complaints), and comments. -- **`/models`**: Gorm database models representing users (Faculty, Warden, Centrehead, Admin), posts, and comments. -- **`/routes`**: API routing configurations for both user actions and administrative control. -- **`/middleware`**: Backend middleware including authentication and permissions checking. -- **`/test`**: Go backend test suite verifying auth flows, complaint management, and administrative actions. - -## Quick Links -- [[Local Setup|Local-Setup]] -- [[Architecture & Flows|Architecture-and-Flows]] -- [[API Reference|API-Reference]] -- [[Contributing|Contributing]] diff --git a/docs/Local-Setup.md b/docs/Local-Setup.md deleted file mode 100644 index 9de4122..0000000 --- a/docs/Local-Setup.md +++ /dev/null @@ -1,61 +0,0 @@ -# Local Setup - -This guide will help you get CMS Web running locally on your development machine. The project is split into a Go backend and a React + TypeScript frontend. - -## Prerequisites - -Ensure you have the following installed: -- [Go](https://go.dev/dl/) (version 1.20+) -- [Node.js](https://nodejs.org/en) (v18+) and npm -- A relational database (SQLite by default or PostgreSQL/MySQL depending on configuration) - ---- - -## 1. Backend Setup - -The backend is built in Go using the **Gin** framework and **GORM**. - -1. Navigate to the root directory of the project. -2. Create your `.env` configuration file from the example: - ```bash - cp .env.example .env - ``` - Configure your database credentials and secret keys inside `.env`. -3. Install the dependencies: - ```bash - go mod download - ``` -4. Run the backend server: - ```bash - go run main.go - ``` - The backend should now be running on its configured port (typically `:8080`). - ---- - -## 2. Frontend Setup - -The frontend is located in the `/app` folder. - -1. Navigate to the `/app` directory: - ```bash - cd app - ``` -2. Install dependencies: - ```bash - npm install - ``` -3. Run the Vite development server: - ```bash - npm run dev - ``` -4. Open the local address printed in the terminal (usually `http://localhost:5173`) in your browser. - ---- - -## 3. Running Tests - -To verify that everything is working as expected, run the Go test suite: -```bash -go test -v ./test/... -``` diff --git a/routes/admin.go b/routes/admin.go index 3981ed6..b158a57 100644 --- a/routes/admin.go +++ b/routes/admin.go @@ -26,9 +26,9 @@ func AdminRoutes (e *gin.Engine, h *handlers.AdminHandler) { // get the posts according to the status posts := e.Group("/api/admin") { - posts.GET("xen/posts", middleware.IsAuthenticated(), h.GetXENPosts) - posts.GET("ae/posts", middleware.IsAuthenticated(), h.GetAEPosts) - posts.GET("je/posts", middleware.IsAuthenticated(), h.GetJEPosts) + posts.GET("/xen/posts", middleware.IsAuthenticated(), h.GetXENPosts) + posts.GET("/ae/posts", middleware.IsAuthenticated(), h.GetAEPosts) + posts.GET("/je/posts", middleware.IsAuthenticated(), h.GetJEPosts) } // for any post