|
1 | 1 | --- |
2 | | -title: Developer Endpoints |
3 | | -description: Technical documentation for Singularity API routes and integrations. |
| 2 | +title: Analytics and API-Driven Features |
| 3 | +description: Feature documentation for student lookup, analytics intelligence, and dashboard data capabilities. |
4 | 4 | --- |
5 | 5 |
|
6 | | -Singularity provides a robust set of API endpoints for programmatic access and internal workflows. This guide covers the main routes used for analytics, organization management, and user verification. |
7 | | - |
8 | | -## Analytics Endpoints 📊 |
9 | | - |
10 | | -### 1. Student Status Distribution |
11 | | -Returns a breakdown of students by academic standing. |
12 | | -- **Endpoint**: `GET /api/analytics/student-status-distribution` |
13 | | -- **Query Params**: |
14 | | - - `year` (optional): Filter by student year. |
15 | | - - `branch` (optional): Filter by department (e.g., CSE, ECE). |
16 | | -- **Response**: |
17 | | - ```json |
18 | | - { |
19 | | - "success": true, |
20 | | - "data": { |
21 | | - "total": 1500, |
22 | | - "distribution": [ |
23 | | - { "status": "Pass", "count": 1200, "percentage": 80 }, |
24 | | - { "status": "PCP", "count": 250, "percentage": 16.67 }, |
25 | | - { "status": "Fail", "count": 50, "percentage": 3.33 } |
26 | | - ] |
27 | | - } |
28 | | - } |
29 | | - ``` |
30 | | - |
31 | | -### 2. Branch Status Breakdown |
32 | | -Returns department-specific performance metrics. |
33 | | -- **Endpoint**: `GET /api/analytics/branch-status-breakdown` |
34 | | -- **Query Params**: |
35 | | - - `year` (optional): Filter by year. |
36 | | - |
37 | | -### 3. Performance Metrics Comparison |
38 | | -Compares metrics between two academic years. |
39 | | -- **Endpoint**: `GET /api/analytics/performance-metrics` |
40 | | -- **Query Params**: |
41 | | - - `years` (required): Comma-separated years (e.g., `years=2,1`). |
42 | | -- **Response**: Includes average SGPA, pass rates, and percentage comparisons. |
| 6 | +This page documents the feature capabilities enabled by the server APIs that power the authenticated analytics dashboard and intelligence workflows. |
43 | 7 |
|
44 | | ---- |
| 8 | +## Student Lookup Features |
45 | 9 |
|
46 | | -## Organization Management 🏢 |
| 10 | +### Student Profile by Roll Number |
47 | 11 |
|
48 | | -### 1. Create Organization |
49 | | -Initializes a new institution with a selected plan. |
50 | | -- **Endpoint**: `POST /api/orgs/create` |
51 | | -- **Body**: |
52 | | - ```json |
53 | | - { |
54 | | - "orgName": "string", |
55 | | - "orgSlug": "string", |
56 | | - "plan": "BASIC | PRO | ENTERPRISE" |
57 | | - } |
58 | | - ``` |
| 12 | +- Endpoint: `GET /api/result/by-rollno` |
| 13 | +- Supports `sem=1..8`, `latest`, and `all`. |
| 14 | +- Enables instant student profile retrieval with semester context. |
| 15 | +- Powers profile cards, semester snapshots, and subject drill-down views. |
59 | 16 |
|
60 | | -### 2. List Organizations |
61 | | -Retrieves a list of organizations the authenticated user belongs to. |
62 | | -- **Endpoint**: `GET /api/orgs/list` |
| 17 | +### Student Collections by Year |
63 | 18 |
|
64 | | -### 3. Membership Requests |
65 | | -Allows students to request to join an organization. |
66 | | -- **Endpoint**: `POST /api/orgs/[orgId]/request` |
| 19 | +- Endpoint: `GET /api/result/by-year` |
| 20 | +- Supports cohort-wide year exploration and filtering. |
| 21 | +- `sem=latest` behavior improves comparison quality by excluding incomplete progressions. |
| 22 | +- Powers year tabs, cohort summaries, and cohort search flows. |
67 | 23 |
|
68 | | ---- |
| 24 | +## Shared Analytics Status Logic |
69 | 25 |
|
70 | | -## User Verification 👤 |
| 26 | +Across analytics endpoints: |
71 | 27 |
|
72 | | -### 1. Student Verification |
73 | | -Updates student profile with academic details. |
74 | | -- **Endpoint**: `POST /api/orguser/verify` |
75 | | -- **Body**: |
76 | | - ```json |
77 | | - { |
78 | | - "rollNo": "string", |
79 | | - "dob": "YYYY-MM-DD", |
80 | | - "year": "number" |
81 | | - } |
82 | | - ``` |
| 28 | +- **Pass**: `0` carry-overs |
| 29 | +- **PCP**: `1-2` carry-overs |
| 30 | +- **Fail**: `>=3` carry-overs |
83 | 31 |
|
84 | 32 | --- |
85 | 33 |
|
86 | | -## Knowledge Base 📚 |
| 34 | +## Analytics Features |
| 35 | + |
| 36 | +### 1) Student Status Distribution |
| 37 | + |
| 38 | +- Endpoint: `GET /api/analytics/student-status-distribution` |
| 39 | +- Filters: `year`, `branch` |
| 40 | +- Feature impact: cohort health pulse (Pass/PCP/Fail). |
| 41 | + |
| 42 | +### 2) Branch Status Breakdown |
| 43 | + |
| 44 | +- Endpoint: `GET /api/analytics/branch-status-breakdown` |
| 45 | +- Filter: `year` |
| 46 | +- Feature impact: branch-level academic strength/risk comparison. |
| 47 | + |
| 48 | +### 3) Year-Branch Comparison |
| 49 | + |
| 50 | +- Endpoint: `GET /api/analytics/year-branch-comparison` |
| 51 | +- Filters: `years`, `branches`, `metric` |
| 52 | +- Feature impact: multi-year trend storytelling across departments. |
| 53 | + |
| 54 | +### 4) Performance Metrics (Two-Year KPI Compare) |
| 55 | + |
| 56 | +- Endpoint: `GET /api/analytics/performance-metrics` |
| 57 | +- Filters: `years=Y1,Y2` (required for new behavior), optional `branch` |
| 58 | +- Feature impact: executive KPI cards with trend direction and percent movement. |
| 59 | + |
| 60 | +### 5) Semester Progression |
| 61 | + |
| 62 | +- Endpoint: `GET /api/analytics/semester-progression` |
| 63 | +- Filters: `year`, `branch` |
| 64 | +- Feature impact: semester growth/decline trajectories. |
| 65 | + |
| 66 | +### 6) SGPA Range Distribution |
| 67 | + |
| 68 | +- Endpoint: `GET /api/analytics/sgpa-range-distribution` |
| 69 | +- Filters: `year`, `branch`, `semester` |
| 70 | +- Feature impact: quality band distribution and concentration analysis. |
| 71 | + |
| 72 | +### 7) Backlog Analysis |
| 73 | + |
| 74 | +- Endpoint: `GET /api/analytics/backlog-analysis` |
| 75 | +- Filters: `year` (required), `branch`, `groupBy` |
| 76 | +- Feature impact: active vs cleared backlog intelligence and intervention guidance. |
| 77 | + |
| 78 | +### 8) Branch Performance Radar |
| 79 | + |
| 80 | +- Endpoint: `GET /api/analytics/branch-performance-radar` |
| 81 | +- Filter: `year` |
| 82 | +- Feature impact: multi-dimensional branch benchmarking. |
| 83 | + |
| 84 | +### 9) Top Performers |
| 85 | + |
| 86 | +- Endpoint: `GET /api/analytics/top-performers` |
| 87 | +- Filters: `limit`, `year`, `branch`, `metric` |
| 88 | +- Feature impact: achiever spotlight and leaderboard modules. |
| 89 | + |
| 90 | +## Analytics Visual Gallery |
| 91 | + |
| 92 | +Analytics chart screenshots use the public URL path `/assets/graphs/*`, backed by files stored in `apps/landing/public/assets/graphs`. |
| 93 | +These are example visualizations generated from the analytics features documented above. |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | + |
| 100 | + |
| 101 | + |
| 102 | + |
| 103 | +## Playground Intelligence Contract |
87 | 104 |
|
88 | | -### 1. Document Submission |
89 | | -Uploads institutional files for AI indexing. |
90 | | -- **Endpoint**: `POST /api/knowledge/submit` |
91 | | -- **Body**: `FormData` containing `documents` (File[]), `orgId`, and `orgName`. |
| 105 | +- `POST /api/playground/optimize` transforms natural language into structured analytics intent. |
| 106 | +- `GET /api/playground/query?text=...` resolves intent to analytics data payloads. |
| 107 | +- Enables admin experimentation workflows for chart-first data exploration. |
92 | 108 |
|
93 | 109 | --- |
94 | 110 |
|
95 | | -## Authentication & Security 🔒 |
| 111 | +## Product Snapshots Connected to Analytics Experience |
96 | 112 |
|
97 | | -- **Auth Provider**: Clerk (Next.js Clerk Middleware). |
98 | | -- **API Keys**: Client-side Gemini API keys are sent via the `x-api-key` header. |
99 | | -- **Authorization**: Protected routes require a valid session cookie from Clerk. |
| 113 | + |
| 114 | + |
0 commit comments