feat: add API endpoints and documentation

README.md

@@ -30,3 +30,66 @@ Simply click the **Duplicate this Space** button in the settings menu of this Sp
 2. Select **Docker** as the SDK.
 3. Upload these files to your Space.
 4. The application will build and run automatically (Port 7860).
+
+## 📡 API Documentation
+
+You can interact with the application programmatically using the following JSON endpoints.
+
+### 1. Analyze Student (`POST /api/analyze`)
+
+Submit student marks to get grade and personality trait.
+
+**Request:**
+
+```json
+POST /api/analyze
+Content-Type: application/json
+
+{
+  "name": "John Doe",
+  "sub1": 85,
+  "sub2": 90,
+  "sub3": 88
+}
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "name": "John Doe",
+    "average": 88,
+    "grade": "A",
+    "trait": "Extroverted"
+  }
+}
+```
+
+### 2. Get Recent Students (`GET /api/students`)
+
+Returns a list of the 10 most recently analyzed students.
+
+**Response:**
+
+```json
+[
+  {
+    "id": 1,
+    "name": "Alice",
+    "subject1": 80,
+    "subject2": 85,
+    "subject3": 90
+  },
+  ...
+]
+```
+
+### 3. Get Rules (`GET /api/rules`)
+
+Returns the grading rules and score ranges.
+
+### 4. Get Traits (`GET /api/traits`)
+
+Returns the mapping of grades to personality traits.

app.js

@@ -7,6 +7,7 @@ const app = express();
 const PORT = process.env.PORT || 7860;
 app.set("view engine", "ejs");
 app.use(bodyParser.urlencoded({ extended: true }));
+app.use(express.json()); // Support JSON bodies for API
 app.use(express.static(path.join(__dirname, 'public')));
 
 // Connect to SQLite Database (File-based)
@@ -37,6 +38,95 @@ app.get("/", (req, res) => {
   });
 });
 
+// --- API Endpoints ---
+
+// Get recent students
+app.get("/api/students", (req, res) => {
+    db.all("SELECT * FROM sampleStudent ORDER BY id DESC LIMIT 10", [], (err, rows) => {
+        if (err) {
+            res.status(500).json({ error: err.message });
+            return;
+        }
+        res.json(rows);
+    });
+});
+
+// Get grading rules
+app.get("/api/rules", (req, res) => {
+    db.all("SELECT * FROM grade_rules ORDER BY min_avg DESC", [], (err, rows) => {
+        if (err) {
+             res.status(500).json({ error: err.message });
+             return;
+        }
+        res.json(rows);
+    });
+});
+
+// Get personality traits
+app.get("/api/traits", (req, res) => {
+    db.all("SELECT * FROM personality_traits", [], (err, rows) => {
+        if (err) {
+            res.status(500).json({ error: err.message });
+            return;
+        }
+        res.json(rows);
+    });
+});
+
+// Analyze student and save result
+app.post("/api/analyze", (req, res) => {
+    const { name, sub1, sub2, sub3 } = req.body;
+    
+    if (!name || sub1 === undefined || sub2 === undefined || sub3 === undefined) {
+        return res.status(400).json({ error: "Missing required fields: name, sub1, sub2, sub3" });
+    }
+
+    const s1 = parseInt(sub1);
+    const s2 = parseInt(sub2);
+    const s3 = parseInt(sub3);
+    const avg = Math.round((s1 + s2 + s3) / 3);
+
+    // 1. Insert Student
+    const insertQuery = `INSERT INTO sampleStudent (name, subject1, subject2, subject3) VALUES (?, ?, ?, ?)`;
+    
+    db.run(insertQuery, [name, s1, s2, s3], function(err) {
+      if (err) {
+        return res.status(500).json({ error: "Error saving student data: " + err.message });
+      }
+  
+      // 2. Find Grade
+      const gradeQuery = `SELECT grade FROM grade_rules WHERE ? >= min_avg AND ? <= max_avg LIMIT 1`;
+  
+      db.get(gradeQuery, [avg, avg], (err, gradeRow) => {
+        if (err || !gradeRow) {
+            return res.status(404).json({ error: "Grade not found for average: " + avg });
+        }
+        
+        const grade = gradeRow.grade;
+  
+        // 3. Find Trait
+        const traitQuery = `SELECT trait FROM personality_traits WHERE grade = ?`;
+        db.get(traitQuery, [grade], (err, traitRow) => {
+           if (err || !traitRow) {
+             return res.status(404).json({ error: "Trait not found for grade: " + grade });
+           }
+  
+           res.json({
+               success: true,
+               data: {
+                   name,
+                   average: avg,
+                   grade,
+                   trait: traitRow.trait
+               }
+           });
+        });
+      });
+    });
+});
+
+// --- End API Endpoints ---
+
 app.post("/result", (req, res) => {
   const { name, sub1, sub2, sub3 } = req.body;