Documentation Guidelines
Recommended Documentation Tools
- Markdown + GitHub Wiki / Nextra: Easy to version, collaborate, and keep close to code.
- Swagger/OpenAPI: For auto-generating and sharing API documentation.
- dbdiagram.io / SchemaSpy / Mermaid: For visualizing and documenting your database schema.
For migration projects, Markdown in a Git repo (with diagrams as images or links) is often the most practical and future-proof.
Example Documentation Structure & Sample Content
1. Project Overview
# Acharya University Backend Migration
## Purpose
Document the current backend system to support migration to a new, maintainable architecture.
## Scope
- Focus: Backend (Spring Boot, Java)
- Out of Scope: Frontend, UI/UX2. Module Overview
# Module Overview
| Module | Description | Key Endpoints (example) |
| --------- | --------------------------------------------- | ----------------------- |
| Student | Manages student admission, fees, ledger, etc. | /api/student/\*\* |
| Employee | Employee records, payroll, attendance | /api/employee/\*\* |
| Academic | Courses, timetable, attendance | /api/academic/\*\* |
| Inventory | Stock, assets, purchase orders | /api/inventory/\*\* |
| Hostel | Hostel beds, attendance, mess | /api/hostel/\*\* |
| ... | ... | ... |3. API Documentation
- Auto-generate with Swagger/OpenAPI (already partially set up in your code).
- Export as HTML or Markdown and link in your docs.
- Example:
# API Endpoints
## Student Module
### POST /api/student/admission
- **Description:** Admit a new student
- **Request Body:** `{ name, dob, ... }`
- **Response:** `201 Created` with student ID
### GET /api/student/{id}
- **Description:** Get student details
- **Response:** Student object4. Data Model
- ER Diagram: Use dbdiagram.io or SchemaSpy to generate a visual diagram.
- Model-to-Table Mapping:
# Data Model
## Student Table
| Field | Type | Description |
| ------------- | ------- | -------------- |
| id | int | Primary key |
| name | varchar | Student name |
| admissionDate | date | Admission date |
| ... | ... | ... |
## Relationships
- Student :left_right_arrow: Fee (one-to-many)
- Student :left_right_arrow: Hostel (one-to-one)5. Business Logic / Flows
# Business Flows
## Student Admission
1. User submits admission form (API: /api/student/admission)
2. System creates student record
3. Fee allocation is triggered (API: /api/finance/fee)
4. Admission confirmation sent
## Employee Attendance
1. Biometric event received (API: /api/employee/attendance)
2. Attendance record updated
3. Payroll calculation scheduled6. Integration Points
# Integrations
- Redis: Caching and session management
- IVR: Student/employee notifications
- WhatsApp: Automated messaging
- External Payroll: For salary disbursement7. Known Issues / Technical Debt
# Known Issues
- Many tables lack foreign key constraints
- Duplicate business logic in multiple services
- Inconsistent API naming conventions
- Some endpoints lack validation8. Migration Notes
# Migration Considerations
- Prioritize modules with the most business value or pain points
- Refactor data model to enforce constraints
- Standardize API structure and error handling
- Incrementally migrate and test each moduleHow to Work as a Team
- Divide modules among team members.
- Daily syncs to share findings and update documentation.
- Central repo (e.g., GitHub) for all docs, diagrams, and API exports.
- Review sessions with the 1-2 project experts for accuracy.
Summary Table
| Step | Tool/Format | Output Example |
|---|---|---|
| API Docs | Swagger/OpenAPI | HTML/Markdown export |
| Data Model | dbdiagram.io | PNG/ERD diagram |
| Module/Feature Docs | Markdown/Confluence | .md files, tables, diagrams |
| Collaboration | GitHub/Notion | Centralized, versioned docs |
Last updated on