Web Builder

Functional Logic

Project: School Management Website
✓ Document Approved
This document has been approved and is currently locked.
Document Title
Status
Document Content
# FUNCTIONAL LOGIC DOCUMENT

**Project Name:** School Management Website  
**Document Version:** 1.1.0  
**Stage:** Functional Logic  
**Author:** Software Project Architect  
**Status:** Under Review  

---

## 1. Overview & Objectives

The purpose of this document is to define the functional behavior, operational flow, and interaction logic for the **School Management Website** based on the approved Project Understanding, Logical Roadmap, and Database Design documents.

This document outlines:
* Forms and their interactive fields
* Input validation logic (distinguishing confirmed data requirements from technical recommendations)
* Conceptual application routes and action handling
* Underlying database query logic (illustrative and conditional)
* End-to-end execution workflows for each confirmed feature

In strict compliance with project governance rules, all items are transparently categorized into:
* **Confirmed Requirements:** Explicitly stated or previously approved project capabilities.
* **AI Recommendations:** Architecture, usability, and technical suggestions proposed for improvement.
* **Open Decisions:** Critical choices that remain unresolved and pending stakeholder confirmation.

---

## 2. Scope Alignment

### 2.1 Confirmed Requirements (Explicit Scope)
The functional logic defined in this document strictly serves the following user-confirmed capabilities:
1. **Add Student:** Capturing and storing Student Name, Email, Phone, Course, and Admission Date.
2. **View Students:** Displaying existing student records.
3. **Edit Student:** Modifying existing student details.
4. **Delete Student:** Removing student records from the system.
5. **Search Student List:** Searching the records.
6. **Filter Student List:** Filtering the records based on criteria.

### 2.2 Unconfirmed / Pending Items (Not Part of Confirmed Baseline)
The following are explicitly **not** confirmed requirements and are treated as AI Recommendations or Open Decisions:
* Specific validation rules (min/max length, format checks, uniqueness constraints).
* Specific route naming conventions or URL paths.
* Specific search target fields (e.g., Name, Email, Phone).
* Specific filter target fields and filtering behavior (e.g., Course dropdown, Admission Date ranges).
* Deletion implementation mechanism (Hard Delete vs. Soft Delete).
* System fields (`id`, `created_at`, `updated_at`, `deleted_at`).
* Admin authentication mechanisms.
* Pagination and UI flash messaging.

---

## 3. Forms & Input Logic

### 3.1 Student Entry / Edit Form (`StudentForm`)

Used conceptually to collect or modify student record data for the Add Student and Edit Student features.

#### Form Fields Definition

| Field Name | Confirmed Data Field | Input Element | Status | AI Recommendation / Alternative |
| :--- | :--- | :--- | :--- | :--- |
| `name` | Student Name | Text Input | Confirmed Requirement | Trim whitespace; 2–150 character limit. *(AI Recommendation)* |
| `email` | Student Email | Text / Email Input | Confirmed Requirement | Validate standard email format. *(AI Recommendation)*<br>Enforce unique email constraint. *(Open Decision)* |
| `phone` | Student Phone | Text / Tel Input | Confirmed Requirement | Digits/dialing characters only (`+`, `-`, spaces); 7–20 character limit. *(AI Recommendation)* |
| `course` | Student Course | Text Input **OR** Dropdown | Confirmed Requirement | **Option A:** Free-text input field.<br>**Option B:** Predefined select dropdown. *(Open Decision)* |
| `admission_date` | Student Admission Date | Date Input | Confirmed Requirement | Standard calendar date picker (`YYYY-MM-DD`). *(AI Recommendation)* |

#### Validation Logic Classification
* **Confirmed Scope:** The system must accept, handle, and store values for all five confirmed fields (`name`, `email`, `phone`, `course`, `admission_date`).
* **Validation Rules (AI Recommendation):** It is recommended to perform both client-side and server-side checks to ensure fields are not blank, text lengths are within reasonable bounds, email follows standard email syntax, and dates represent valid calendar entries.
* **Email Uniqueness Validation (Open Decision):** Whether the system should reject a submission if the email already belongs to another student is not yet confirmed and remains an open question.

---

### 3.2 Search & Filter Form (`DirectoryFilterForm`)

Positioned on the student directory view to provide search and filter capabilities.

#### Fields Definition

| Control | Target / Purpose | Input Element | Classification | Status & Notes |
| :--- | :--- | :--- | :--- | :--- |
| **Search Input** | Search student records | Text Input | Confirmed Requirement (Search Feature) | Exact target search fields (e.g., searching Name, Email, or Phone) are an **AI Recommendation / Open Decision**. |
| **Course Filter** | Narrow list by course | Free text **OR** Select Dropdown | AI Recommendation | Course filter is a recommendation; actual filter fields remain an **Open Decision**. |
| **Admission Date Filter** | Narrow list by date | Date Input / Date Range | AI Recommendation | Admission date filter is a recommendation; exact matching behavior remains an **Open Decision**. |
| **Reset Filters** | Clear search/filter inputs | Action Button / Link | AI Recommendation | Usability enhancement to return to the full list view. |

---

## 4. Application Routes & Endpoint Flow (Conceptual)

The routes below are **illustrative, framework-agnostic architectural recommendations** representing standard RESTful patterns. They do not constitute user-mandated specifications.

| Conceptual Route | HTTP Method | Associated Feature | Input / Parameters | Expected Behavior | Classification |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `/students` | `GET` | View Students / Search / Filter | Query Params *(Illustrative)*: `search`, `course`, `date` | Retrieve and render student list matching search/filter criteria. | AI Recommendation (Pattern for CF-02, CF-05, CF-06) |
| `/students/create` | `GET` | Add Student (Form Display) | None | Render the empty student data entry form. | AI Recommendation (Pattern for CF-01) |
| `/students` | `POST` | Add Student (Persistence) | Payload: `name`, `email`, `phone`, `course`, `admission_date` | Process submitted student data and save record. | AI Recommendation (Pattern for CF-01) |
| `/students/{id}/edit` | `GET` | Edit Student (Form Display) | Identifier: `{id}` *(AI-recommended record identifier)* | Retrieve existing student data and render the pre-populated edit form. | AI Recommendation (Pattern for CF-03) |
| `/students/{id}` | `PUT` / `POST` | Edit Student (Update) | Identifier: `{id}`<br>Payload: `name`, `email`, `phone`, `course`, `admission_date` | Update existing student record with modified values. | AI Recommendation (Pattern for CF-03) |
| `/students/{id}/delete` | `POST` / `DELETE` | Delete Student | Identifier: `{id}` *(AI-recommended record identifier)* | Execute record deletion according to the chosen deletion strategy. | AI Recommendation (Pattern for CF-04) |

*(Note on Access Control: Whether these routes are behind an Admin Authentication gate or are directly accessible within the host network remains an **Open Decision**).*

---

## 5. Database Operations & Query Logic

*Note: All SQL examples below are illustrative, based on the baseline schema established in the Database Design Document. The unique record identifier `{id}` and timestamps are AI-recommended schema fields.*

### 5.1 Add Student (Insert)
* **Operation:** Store a new student record containing confirmed fields.
* **Illustrative Query:**
  ```sql
  INSERT INTO students (name, email, phone, course, admission_date, created_at, updated_at)
  VALUES (:name, :email, :phone, :course, :admission_date, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
  ```

### 5.2 View Students Directory (Read)
* **Operation:** Fetch student records from the students table.
* **Illustrative Query:**
  ```sql
  SELECT id, name, email, phone, course, admission_date 
  FROM students 
  ORDER BY id DESC;
  ```

### 5.3 Edit Student (Fetch & Update)
* **Fetch for Edit Display:**
  ```sql
  SELECT id, name, email, phone, course, admission_date 
  FROM students 
  WHERE id = :id;
  ```
* **Persist Modifications:**
  ```sql
  UPDATE students 
  SET name = :name, 
      email = :email, 
      phone = :phone, 
      course = :course, 
      admission_date = :admission_date, 
      updated_at = CURRENT_TIMESTAMP 
  WHERE id = :id;
  ```

### 5.4 Delete Student Operations (Alternative Approaches)
The project requires the ability to delete student records, but the deletion strategy remains an **Open Decision**.

* **Alternative 1: Hard Delete (Permanent Removal)**
  ```sql
  DELETE FROM students WHERE id = :id;
  ```
* **Alternative 2: Soft Delete (Archival / Timestamp Marker - AI Recommendation)**
  * *Applies only if Soft Delete is explicitly approved and the `deleted_at` field is added to the database schema.*
  ```sql
  UPDATE students SET deleted_at = CURRENT_TIMESTAMP WHERE id = :id;
  ```

### 5.5 Search and Filter Operations (Dynamic Construction)
The system must support searching and filtering student records. The exact matching fields remain an **Open Decision**. Below is an illustrative dynamic query model demonstrating how search and filter parameters can be combined conditionally without conflicting:

* **Base Query Structure:**
  ```sql
  SELECT id, name, email, phone, course, admission_date 
  FROM students 
  WHERE 1=1
  ```
* **Conditional Search Clause (AI Recommendation — Pending Search Scope Decision):**
  * If a search string is provided, apply matching conditions across designated search fields (e.g., matching name, email, or phone):
    ```sql
    AND (name LIKE :search OR email LIKE :search OR phone LIKE :search)
    ```
* **Conditional Filter Clauses (AI Recommendation — Pending Filter Scope Decision):**
  * If a course filter value is provided:
    ```sql
    AND course = :filter_course
    ```
  * If an admission date filter value is provided:
    ```sql
    AND admission_date = :filter_admission_date
    ```
* **Conditional Soft Delete Clause (Conditional on Alternative 2 approval only):**
  * If Soft Delete is adopted:
    ```sql
    AND deleted_at IS NULL
    ```
  * *(Note: `deleted_at` is not part of the baseline schema and must not be used if Hard Delete is selected).*

---

## 6. End-to-End Functional Workflows

### 6.1 Workflow: Add Student
```text
[ Admin initiates Add Student ]
              │
              ▼
    [ Display StudentForm ]
              │
              ▼
   [ Admin submits student fields ]
   (name, email, phone, course, admission_date)
              │
              ▼
   [ Validate Input Data ] ── (AI Recommendation)
        ├── [ Validation Fails ] ──► Re-render form with field error messages
        └── [ Validation Passes ] ──► Execute Database INSERT
                                           │
                                           ▼
                               [ Set success notification ] ── (AI Recommendation)
                                           │
                                           ▼
                               [ Redirect to Student List ] ── (AI Recommendation)
```

### 6.2 Workflow: View Students with Combined Search & Filter
```text
[ Admin views directory OR submits Search/Filter criteria ]
                         │
                         ▼
             [ Receive Query Parameters ]
       (Search query, Filter criteria - if supplied)
                         │
                         ▼
        [ Construct dynamic database query ]
    (Combines active search and filter conditions via AND)
                         │
                         ▼
           [ Execute query against storage ]
                         │
                         ▼
        [ Render Student Directory Table ]
  (Displays matching records OR displays empty state message)
  (Optional: Pagination controls - AI Recommendation)
```

### 6.3 Workflow: Edit Student
```text
[ Admin selects "Edit" on a specific student record ]
                         │
                         ▼
          [ Fetch record using record ID ]
        ├── [ Record Not Found ] ──► Display error / redirect ── (AI Recommendation)
        └── [ Record Found ] ─────► Pre-populate and render StudentForm
                                          │
                                          ▼
                [ Admin modifies fields and submits form ]
                                          │
                                          ▼
                  [ Validate Input Data ] ── (AI Recommendation)
        ├── [ Validation Fails ] ──► Re-render form with current inputs & error messages
        └── [ Validation Passes ] ──► Execute Database UPDATE for record
                                          │
                                          ▼
                               [ Set success notification ] ── (AI Recommendation)
                                          │
                                          ▼
                               [ Redirect to Student List ] ── (AI Recommendation)
```

### 6.4 Workflow: Delete Student
```text
[ Admin initiates "Delete" on a student record ]
                         │
                         ▼
    [ Prompt confirmation dialog ] ── (AI Recommendation)
        ├── [ Cancelled ] ──► Abort operation; maintain current view
        └── [ Confirmed ] ──► Submit deletion request
                                     │
                                     ▼
                      [ Check if record exists in DB ]
        ├── [ Record Not Found ] ──► Return error message ── (AI Recommendation)
        └── [ Record Exists ] ────► Execute Deletion based on chosen strategy:
                                    • Option A: Permanent DELETE (Hard Delete)
                                    • Option B: Timestamp update (Soft Delete, if approved)
                                     │
                                     ▼
                         [ Set success notification ] ── (AI Recommendation)
                                     │
                                     ▼
                         [ Redirect to Student List ] ── (AI Recommendation)
```

---

## 7. Open Decisions

The following functional and technical decisions remain open and require resolution prior to coding:

1. **Deletion Strategy:**
   * *Status:* Open Decision.
   * Will student deletion be executed as a permanent **Hard Delete** (`DELETE FROM students`) or an archived **Soft Delete** (`deleted_at` timestamp column)?

2. **Search Target Scope:**
   * *Status:* Open Decision.
   * Which specific fields should the search bar query against? *(AI Recommendation: Search across `name`, `email`, and `phone`).*

3. **Filter Target Scope & Behavior:**
   * *Status:* Open Decision.
   * Which specific fields should be filterable? *(AI Recommendation: Filter by `course` and `admission_date`).*
   * For `admission_date`, will filtering match an exact date or a date range?

4. **Course Value Input Method:**
   * *Status:* Open Decision.
   * Should the `course` field be entered as free text or selected from a predefined list/dropdown?

5. **Email Uniqueness Constraint:**
   * *Status:* Open Decision.
   * Should duplicate email addresses across multiple student records be rejected or permitted?

6. **Admin Authentication & Access Control:**
   * *Status:* Open Decision.
   * Is a login/credential system required before administrative routes can be accessed, or will the system operate within an already-secured environment?

7. **Pagination:**
   * *Status:* Open Decision / AI Recommendation.
   * Should pagination controls be introduced to paginate the student directory table?

---

## 8. Web Builder Workflow & Next Steps

This project strictly adheres to the established Web Builder sequential workflow:

```text
Project Understanding
        ↓
Project Proposal
        ↓
Logical Roadmap
        ↓
Database Design
        ↓
Functional Logic  ◄ [CURRENT STAGE]
        ↓
Verification      ◄ [NEXT STAGE]
        ↓
UI Design
        ↓
Coding Structure
```

### Next Steps:
1. Review and approve this **Functional Logic Document**.
2. Resolve any critical **Open Decisions** (such as Deletion Strategy, Course Input Format, Search/Filter Scope).
3. Proceed directly to the next stage: **Verification** (where test cases, acceptance criteria, and requirement verification matrices will be documented).
✓ Approved & Locked Cancel
Stage Information
Functional Logic

Har functionality ka detailed working logic define karna.
Expected Output

Forms, fields, validations, routes, actions, database operations and workflows.
Previous Stages
Project Understanding
✓ Available
Logical Roadmap
✓ Available
Database Design
✓ Available
AI Generation
Stage Ready
All required previous stages are approved.
✓ This document is approved and locked.
Rework with AI
✓ Document Approved
Rework is disabled because this document has been approved.