{"openapi":"3.0.3","info":{"title":"ERP Backend API","version":"1.0.0","description":"API documentation for the ERP backend."},"servers":[{"url":"http://localhost:5000","description":"Local development server"}],"tags":[{"name":"Student Auth","description":"Student signup and login endpoints"},{"name":"Staff Auth","description":"Staff portal login (all non-student roles)"},{"name":"Auth","description":"Session and profile endpoints"},{"name":"Navigation","description":"Role-aware sidebar navigation tree"},{"name":"Academics","description":"Academic masters (years, semesters, departments, programs, courses, batches). GET requires academics.view or academics.manage; POST/PATCH/DELETE require academics.manage."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid email or password"}}},"StudentSignupRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"student@example.com"},"password":{"type":"string","minLength":8,"example":"password123"},"firstName":{"type":"string","example":"Rahul"},"lastName":{"type":"string","example":"Sharma"}}},"StudentLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"student@example.com"},"password":{"type":"string","minLength":8,"example":"password123"}}},"StaffLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"admin@example.com"},"password":{"type":"string","minLength":8,"example":"password123"}}},"AdminLoginRequest":{"$ref":"#/components/schemas/StaffLoginRequest"},"PersonSummary":{"type":"object","properties":{"id":{"type":"integer","example":1},"firstName":{"type":"string","example":"Rahul"},"middleName":{"type":"string","nullable":true},"lastName":{"type":"string","example":"Sharma"},"fullName":{"type":"string","example":"Rahul Sharma"},"phone":{"type":"string","nullable":true},"dob":{"type":"string","format":"date","nullable":true},"gender":{"type":"string","enum":["MALE","FEMALE","OTHER"],"nullable":true},"photoUrl":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"campusId":{"type":"integer","nullable":true}}},"AuthUser":{"type":"object","properties":{"id":{"type":"string","example":"clx123abc0000abcd1234efgh"},"email":{"type":"string","format":"email","example":"student@example.com"},"isActive":{"type":"boolean","example":true},"lastLoginAt":{"type":"string","format":"date-time","nullable":true},"role":{"type":"object","properties":{"id":{"type":"integer","example":6},"roleName":{"type":"string","example":"Student"}}},"person":{"allOf":[{"$ref":"#/components/schemas/PersonSummary"}],"nullable":true},"profileKind":{"type":"string","enum":["student","faculty","staff"],"nullable":true},"studentProfile":{"type":"object","nullable":true},"facultyProfile":{"type":"object","nullable":true},"staffProfile":{"type":"object","nullable":true}}},"NavigationItem":{"type":"object","properties":{"id":{"type":"integer","example":1},"slug":{"type":"string","example":"users"},"title":{"type":"string","example":"Users"},"url":{"type":"string","example":"#"},"iconName":{"type":"string","nullable":true,"example":"Users"},"section":{"type":"string","example":"main"},"permission":{"type":"string","nullable":true,"example":"users.view"},"sortOrder":{"type":"integer","example":20},"children":{"type":"array","items":{"$ref":"#/components/schemas/NavigationItem"}}}},"NavigationTreeResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Navigation fetched successfully"},"data":{"type":"object","properties":{"main":{"type":"array","items":{"$ref":"#/components/schemas/NavigationItem"}},"secondary":{"type":"array","items":{"$ref":"#/components/schemas/NavigationItem"}}}}}},"AuthResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Student login successful"},"data":{"type":"object","properties":{"token":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"user":{"$ref":"#/components/schemas/AuthUser"},"permissions":{"type":"array","items":{"type":"string"},"example":["academics.view"]}}}}}}},"paths":{"/api/academics/schools":{"get":{"summary":"List schools","tags":["Academics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"campusId","schema":{"type":"integer"}},{"in":"query","name":"includeInactive","schema":{"type":"boolean"}}]},"post":{"summary":"Create school","tags":["Academics"],"security":[{"bearerAuth":[]}]}},"/api/academics/departments":{"get":{"summary":"List departments","tags":["Academics"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"schoolId","schema":{"type":"integer"}},{"in":"query","name":"includeInactive","schema":{"type":"boolean"}}]},"post":{"summary":"Create department","tags":["Academics"],"security":[{"bearerAuth":[]}]}},"/api/academics/courses":{"get":{"summary":"List courses","tags":["Academics"],"security":[{"bearerAuth":[]}]},"post":{"summary":"Create course","tags":["Academics"],"security":[{"bearerAuth":[]}]}},"/api/academics/batches":{"get":{"summary":"List class sections (batches)","tags":["Academics"],"security":[{"bearerAuth":[]}]},"post":{"summary":"Create batch","tags":["Academics"],"security":[{"bearerAuth":[]}]}},"/api/auth/student/signup":{"post":{"summary":"Create a student account","tags":["Student Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentSignupRequest"}}}},"responses":{"201":{"description":"Student signup successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Student role or active institution not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Email is already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/auth/student/login":{"post":{"summary":"Login with student credentials","tags":["Student Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentLoginRequest"}}}},"responses":{"200":{"description":"Student login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid student credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/auth/admin/login":{"post":{"summary":"Login with staff portal credentials (all non-student roles)","tags":["Staff Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminLoginRequest"}}}},"responses":{"200":{"description":"Staff portal login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid staff portal credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/auth/staff/login":{"post":{"summary":"Login with staff portal credentials (all non-student roles)","tags":["Staff Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffLoginRequest"}}}},"responses":{"200":{"description":"Staff portal login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Invalid credentials or wrong portal"}}}},"/api/auth/me":{"get":{"summary":"Get current authenticated session (user, person, profiles, permissions)","tags":["Auth"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current session with person and role profile data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"Not authenticated"}}}},"/api/navigation":{"get":{"summary":"Get navigation tree for the authenticated role","description":"Returns the sidebar navigation items visible to the role embedded in the access token, grouped by section.","tags":["Navigation"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Navigation tree fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NavigationTreeResponse"}}}},"401":{"description":"Missing or invalid access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}