> ## Documentation Index
> Fetch the complete documentation index at: https://docs.criar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Admission Form

> Public-facing enrollment workflow that captures student, parent, and guardian data without requiring authentication.

## 1. API Purpose

The Admission Form API digitizes the enrollment process. It allows prospective parents to submit their data through a multi-step form, which then automatically populates the core student and parent registries.

***

## 2. Endpoint Definition

| Method | Route                     | Auth      | Description                         |
| ------ | ------------------------- | --------- | ----------------------------------- |
| POST   | `/web-app/admission-form` | 🔓 Public | Submit full admission data          |
| GET    | `/web-app/student-info`   | 🔓 Public | Lookup existing info by roll number |
| GET    | `/web-app/grades`         | 🔓 Public | List available grades for a school  |
| PATCH  | `/web-app/update-student` | 🔓 Public | Update specific admission sections  |

***

## 3. Authentication Flow

**Zero-Auth Flow:** These endpoints are marked as `@Public()` and do not require a JWT. This allows new parents who are not yet in the system to submit their data. Security is maintained by requiring a valid `skole_id` in the request body to link data to the correct institution.

***

## 4. Request Structure

#### POST /web-app/admission-form

**Request Body:**

```json theme={null}
{
  "skole_id": "SKL001",
  "student": {
    "student_full_name": "Aarav Sharma",
    "gender": "Male",
    "date_of_birth": "2015-05-15",
    "grade": "Grade 1"
  },
  "parent_details": {
    "father_name": "Rajesh Sharma",
    "father_phone_no": 9876543210,
    "father_email": "rajesh.s@example.com"
  },
  "student_address": {
    "address_type": "permanent",
    "address": "123 School Street",
    "city": "Chennai",
    "state": "Tamil Nadu",
    "pincode": 600001
  }
}
```

#### GET /web-app/student-info

**Query Parameters:**

| Field     | Type   | Required | Description          |
| --------- | ------ | -------- | -------------------- |
| skole\_id | string | Yes      | School identifier.   |
| roll\_no  | string | Yes      | Student roll number. |

#### GET /web-app/grades

**Query Parameters:**

| Field     | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| skole\_id | string | Yes      | School identifier. |

#### PATCH /web-app/update-student

**Request Body:**

```json theme={null}
{
  "blood_group": "AB+",
  "aadhaar_number": "123456789012"
}
```

***

## 5. Response Structure

#### Success: Admission Submitted (201 Created)

**Route:** `POST /web-app/admission-form`

```json theme={null}
{
  "success": true,
  "message": "Admission application received",
  "data": {
    "student": { "id": 105, "roll_no": "20240105", "status": "registered" }
  }
}
```

#### Success: Student Info Lookup (200 OK)

**Route:** `GET /web-app/student-info`

```json theme={null}
{
  "success": true,
  "data": {
    "student_full_name": "Aarav Sharma",
    "grade": "Grade 1",
    "status": "registered"
  }
}
```

#### Success: Grade List (200 OK)

**Route:** `GET /web-app/grades`

```json theme={null}
{
  "success": true,
  "data": [
    { "id": 1, "grade_name": "Grade 1" },
    { "id": 2, "grade_name": "Grade 2" }
  ]
}
```

#### Success: Admission Section Updated (200 OK)

**Route:** `PATCH /web-app/update-student`

```json theme={null}
{
  "success": true,
  "message": "Student profile partially updated"
}
```

***

## 6. Error Responses

| HTTP Code | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| 400       | Missing required fields in one of the sections (student/parent/address) |
| 409       | Student with this roll number already exists                            |

***

## 7. Security Considerations

* **Input Validation:** Strict DTO (Data Transfer Object) validation ensures no malformed data enters the core registry.
* **Tenant Isolation:** Every submission MUST include a valid `skole_id`.

***

## 8. Token Usage

N/A (Public endpoints).

***

## 9. Token Refresh

N/A.

***

## 10. Logout / Session Invalidation

N/A.

***

## 11. Usage Example (cURL)

```bash theme={null}
curl -X POST http://localhost:3000/web-app/admission-form \
-H "Content-Type: application/json" \
-d '{"skole_id": "SKL001", "student": {...}, "parent": {...}}'
```

***

## 12. Notes / Special Behaviors

* **Atomic Transactions:** The admission process uses database transactions. If any section (e.g., Address) fails to save, the entire student and parent creation is rolled back.
* **PIN Setup:** Upon successful submission, a setup link is typically generated for the parent to configure their initial login PIN.