Web Builder

Coding Structure

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

**Project Name:** School Management Website
**Document Version:** 1.0.0
**Stage:** Coding Structure
**Author:** Software Project Architect
**Status:** Under Review

---

## 1. Overview & Objectives

### 1.1 Purpose

This document defines the technical coding structure for the **School Management Website** — including folder organization, pages, routes, controllers/handlers, models, assets, and coding conventions — so that implementation can begin with a clear, consistent scaffold.

It is derived strictly from the approved Project Understanding, Database Design, Functional Logic, Verification, and UI Design documents.

### 1.2 Governance Rules Applied

Per the Verification governance flow, **no Open Decision may be silently resolved within this stage**:

```text
Open Decision
      ↓
AI Recommendation / Alternatives
      ↓
User Approval
      ↓
Confirmed Decision
```

Because the technology stack (OD-1) and database engine (OD-9) remain Open Decisions, this document presents **framework-agnostic structural patterns** and clearly labeled **alternatives**, not a single finalized stack.

---

## 2. Governance Constraints & Blocking Open Decisions

The following Open Decisions directly block finalization of parts of the coding structure. They remain unresolved and are preserved here.

| OD | Decision | Coding Impact | Status |
| :--- | :--- | :--- | :--- |
| OD-1 | Technology stack (language and framework) | Determines folder conventions, controller patterns, routing style | Open Decision |
| OD-2 | Admin authentication approach | Determines presence of auth middleware, login route, session handling | Open Decision |
| OD-3 | Search target fields | Determines query parameters and search handler logic | Open Decision |
| OD-4 | Filter target fields & behavior | Determines filter parameters and query construction | Open Decision |
| OD-5 | Course input method | Determines whether course is a text field or a lookup source | Open Decision |
| OD-6 | Deletion strategy | Determines delete handler SQL (DELETE vs. UPDATE `deleted_at`) | Open Decision |
| OD-7 | Email uniqueness constraint | Determines validation and DB-level unique constraint | Open Decision |
| OD-8 | Pagination requirement | Determines whether pagination logic and controls exist | Open Decision |
| OD-9 | Database engine selection | Determines DB driver, connection config, migration syntax | Open Decision |

This document **does not** resolve any of these. Where structure depends on an Open Decision, alternative layouts are shown and labeled.

---

## 3. Confirmed Coding Requirements

The coding structure must support exactly the following confirmed capabilities. These are the only user-confirmed coding targets.

| Req ID | Capability | UI Surface | Data Fields |
| :--- | :--- | :--- | :--- |
| FR-1 | Add Student | Student Form (Add) | name, email, phone, course, admission_date |
| FR-2 | View Students | Student Directory | All five fields displayed |
| FR-3 | Edit Student | Student Form (Edit) | All five fields editable |
| FR-4 | Delete Student | Directory action | Record removal (strategy per OD-6) |
| FR-5 | Search Student List | Directory search control | Fields per OD-3 |
| FR-6 | Filter Student List | Directory filter controls | Fields per OD-4 |

No additional user-facing features may be introduced at this stage.

---

## 4. Project Structure (Framework-Agnostic)

Because OD-1 is unresolved, the structure below is presented as a **technology-agnostic logical layout**. It maps cleanly onto either a monolithic or decoupled implementation.

### 4.1 Logical Project Layout

```text
school-management/
├── config/                     # Environment & app configuration
│   ├── app.*                   # App-level settings
│   └── database.*              # DB connection config (engine TBD per OD-9)
│
├── routes/                     # Route definitions (see Section 5)
│   └── student_routes.*
│
├── controllers/                # Request handlers (see Section 6)
│   └── StudentController.*
│
├── models/                     # Data access layer (see Section 7)
│   └── StudentModel.*
│
├── views/                      # Page templates / UI surfaces (see Section 5)
│   ├── layout.*
│   ├── directory.*
│   ├── form_add.*
│   ├── form_edit.*
│   ├── partials/
│   │   ├── header.*
│   │   ├── footer.*
│   │   ├── flash.*
│   │   ├── delete_modal.*
│   │   └── empty_state.*
│   └── [login.*]               # Conditional — only if OD-2 resolves to auth
│
├── assets/                     # Static assets
│   ├── css/
│   │   └── app.css
│   ├── js/
│   │   ├── form_validation.js
│   │   └── delete_confirm.js
│   └── img/
│
├── middleware/                 # Optional middleware
│   └── [auth.*]                # Conditional — only if OD-2 resolves to auth
│
├── migrations/                 # DB migration scripts (engine per OD-9)
│   └── create_students_table.*
│
├── tests/                      # Test files (structure recommendation)
│
├── public/                     # Public web root (if applicable to stack)
│
├── .env.example                # Environment variables template
├── README.md                   # Setup documentation
└── [project manifest file]     # e.g., package.json / composer.json / requirements.txt — per OD-1
```

**Classification:** AI Recommendation (structure pattern). Folder names may vary by stack; the logical grouping (routes, controllers, models, views, assets) is the important part.

### 4.2 Alternative Structures Based on OD-1

| If OD-1 resolves to… | Recommended Shape | Classification |
| :--- | :--- | :--- |
| Server-rendered monolith (e.g., Django, Laravel, Express+EJS) | Single project root with `routes/`, `controllers/`, `views/`, `assets/` | AI Recommendation |
| SPA + REST API | Split into `frontend/` (SPA) and `backend/` (API) with shared contracts | AI Recommendation |
| Minimal single-file / micro-framework | Single `app.*` plus a `templates/` and `public/` folder | AI Recommendation |

Final selection requires User Approval per the governance flow.

---

## 5. Pages & Routes

### 5.1 Pages (Views)

Pages match the UI Design document. Coding targets:

| Page ID | View File (illustrative) | UI Source | Feature |
| :--- | :--- | :--- | :--- |
| P-1 | `views/directory.*` | UI Design §5.1 | FR-2, FR-4, FR-5, FR-6 |
| P-2 | `views/form_add.*` | UI Design §5.2 | FR-1 |
| P-3 | `views/form_edit.*` | UI Design §5.3 | FR-3 |
| P-4 (partial) | `views/partials/delete_modal.*` | UI Design §5.4 | FR-4 (AI Recommendation) |
| P-5 (partial) | `views/partials/empty_state.*` | UI Design §5.5 | AI Recommendation |
| P-6 (partial) | `views/partials/flash.*` | UI Design §5.6 | AI Recommendation |
| P-7 (conditional) | `views/login.*` | UI Design §3 (placeholder) | Conditional on OD-2 |

### 5.2 Routes

Routes follow the conceptual patterns from Functional Logic §4. They are **illustrative and framework-agnostic**; exact syntax depends on OD-1.

| Route | Method | Handler | Feature | Status |
| :--- | :--- | :--- | :--- | :--- |
| `/students` | GET | `StudentController.list` | FR-2, FR-5, FR-6 | AI Recommendation (pattern) |
| `/students/create` | GET | `StudentController.showCreate` | FR-1 (form) | AI Recommendation |
| `/students` | POST | `StudentController.create` | FR-1 (persist) | AI Recommendation |
| `/students/{id}/edit` | GET | `StudentController.showEdit` | FR-3 (form) | AI Recommendation |
| `/students/{id}` | PUT/POST | `StudentController.update` | FR-3 (persist) | AI Recommendation |
| `/students/{id}/delete` | POST/DELETE | `StudentController.delete` | FR-4 | AI Recommendation |
| `/login` | GET/POST | `AuthController.*` | OD-2 | Conditional — Open Decision |

**Note:** Route naming, method overrides (PUT/DELETE via POST), and URL prefixes are implementation conventions and may be adjusted per OD-1.

---

## 6. Controllers / Handlers

Controllers follow a single-responsibility pattern: one controller for student operations, plus an optional auth controller.

### 6.1 StudentController (Required)

| Method | Responsibility | Reads | Writes | Feature |
| :--- | :--- | :--- | :--- | :--- |
| `list` | Fetch and render directory; apply search/filter per OD-3/OD-4 | Query params (search, filters) | Render P-1 | FR-2, FR-5, FR-6 |
| `showCreate` | Render empty Add form | — | Render P-2 | FR-1 |
| `create` | Validate + persist new student | Form payload | DB insert | FR-1 |
| `showEdit` | Fetch record by id and render Edit form | Route id | Render P-3 | FR-3 |
| `update` | Validate + persist modifications | Route id + payload | DB update | FR-3 |
| `delete` | Execute deletion per OD-6 | Route id | DB delete or soft-delete | FR-4 |

### 6.2 AuthController (Conditional — OD-2)

- Present only if OD-2 resolves to requiring authentication.
- Scope, storage, and session strategy remain Open Decisions.

### 6.3 Controller Conventions (AI Recommendation)

- Keep controllers thin; move query construction into models.
- Validate input before touching the model.
- Return a redirect (to directory) on success; return re-rendered form on validation failure.
- Centralize success/error messages via a flash helper.

---

## 7. Models / Data Access Layer

### 7.1 Student Model

The `students` model wraps all database access for the confirmed student entity.

| Operation | Method (illustrative) | Notes |
| :--- | :--- | :--- |
| List all | `all()` | Supports ordering; pagination per OD-8 |
| Search + Filter | `search(filters)` | Dynamic query per Functional Logic §5.5; scope per OD-3/OD-4 |
| Find by id | `find(id)` | For edit form and delete existence check |
| Insert | `create(data)` | Uses confirmed fields |
| Update | `update(id, data)` | Uses confirmed fields |
| Delete | `delete(id)` | Hard or soft per OD-6 |

### 7.2 Schema Alignment

The model must map to the confirmed fields only:
`name`, `email`, `phone`, `course`, `admission_date`

Optional/recommended fields (`id`, `created_at`, `updated_at`, and conditionally `deleted_at`) remain AI Recommendations from the Database Design document and must be explicitly approved before being relied upon.

### 7.3 Query Construction (Dynamic)

Search and filter clauses follow Functional Logic §5.5:

```text
Base query → conditionally append search clause (per OD-3)
           → conditionally append filter clauses (per OD-4)
           → optionally append deleted_at IS NULL (only if OD-6 = Soft Delete)
```

No final SQL is committed until OD-3, OD-4, and OD-6 are resolved.

---

## 8. Assets

### 8.1 CSS

| Asset | Purpose | Classification |
| :--- | :--- | :--- |
| `assets/css/app.css` | Base styles, layout, responsive rules | AI Recommendation |
| Optional framework (e.g., Bootstrap/Tailwind) | Utility classes and components | AI Recommendation — pending OD-1 |

### 8.2 JavaScript

| Asset | Purpose | Classification |
| :--- | :--- | :--- |
| `assets/js/delete_confirm.js` | Intercepts delete action and shows confirmation modal (P-4) | AI Recommendation (REC-01) |
| `assets/js/form_validation.js` | Client-side validation feedback on forms | AI Recommendation (REC-02) |

### 8.3 Asset Conventions (AI Recommendation)

- Keep CSS in a single app stylesheet unless a framework is chosen.
- Keep JS minimal and progressive — core functionality must still work if JS is disabled (forms submit, directory loads).
- No build tooling is assumed; if OD-1 selects a build-based stack, this section will be revised.

---

## 9. API Structure (Conditional)

If OD-1 resolves to a **decoupled SPA + API** approach, an API layer would be required. This is **not part of the confirmed scope** and is shown only as an alternative.

| Endpoint | Method | Handler | Feature | Status |
| :--- | :--- | :--- | :--- | :--- |
| `/api/students` | GET | `StudentController.list` | FR-2, FR-5, FR-6 | Conditional — AI Recommendation |
| `/api/students` | POST | `StudentController.create` | FR-1 | Conditional — AI Recommendation |
| `/api/students/{id}` | GET | `StudentController.show` | FR-3 (fetch) | Conditional — AI Recommendation |
| `/api/students/{id}` | PUT | `StudentController.update` | FR-3 | Conditional — AI Recommendation |
| `/api/students/{id}` | DELETE | `StudentController.delete` | FR-4 | Conditional — AI Recommendation |

If a server-rendered approach is chosen, this section is not applicable and routes in Section 5 are used directly.

---

## 10. Configuration & Environment

### 10.1 Configuration Items

| Config Area | Contents | Status |
| :--- | :--- | :--- |
| App config | App name, base URL, debug flag | AI Recommendation |
| Database config | Driver, host, credentials (engine per OD-9) | AI Recommendation — depends on OD-9 |
| Session config | Only if OD-2 requires authentication | Conditional — Open Decision |
| Environment variables | Template file `.env.example` | AI Recommendation |

### 10.2 Environment Handling (AI Recommendation)

- Secrets (DB credentials, auth keys) must never be committed.
- Provide a `.env.example` listing required variables.
- The README (a confirmed project deliverable per the Roadmap) will document setup steps.

---

## 11. Coding Conventions (AI Recommendation)

These conventions are suggested for consistency. Final adoption depends on the approved technology stack.

- **Naming:** Consistent casing for files and identifiers per language norms (e.g., `StudentController`, `student_model`).
- **Separation:** Routes → Controllers → Models → Views (no DB calls in views).
- **Validation:** Validate at the controller boundary; mirror rules client-side where a UI benefit exists.
- **Error Handling:** Centralized error handler; user-facing messages via flash; log technical details server-side.
- **Comments:** Comment non-obvious logic; do not restate obvious code.
- **DRY:** Reuse partials for header, footer, flash, delete modal, empty state.

---

## 12. Open Decisions Affecting Coding Structure

This document does **not** resolve any Open Decision. The following decisions affect the final code scaffold and must be resolved (via the governance flow) before or during implementation of the affected area.

| OD | Affected Coding Area |
| :--- | :--- |
| OD-1 | Entire folder structure, language, framework, routing style, asset pipeline |
| OD-2 | Auth routes, middleware, session handling, login view |
| OD-3 | Search query parameters and model query logic |
| OD-4 | Filter query parameters, controls, and model query logic |
| OD-5 | Course field handling in forms, models, and filters |
| OD-6 | Delete handler (hard vs. soft), conditional `deleted_at` clause |
| OD-7 | Email validation logic and possible DB unique constraint |
| OD-8 | Pagination logic in `list()` and directory view |
| OD-9 | DB driver, connection config, migration syntax |

---

## 13. Confirmed Coding Requirements Summary

| Coding Requirement ID | Description | Traces To |
| :--- | :--- | :--- |
| CS-CR-01 | Routes and handlers for Add, View, Edit, Delete student | FR-1 to FR-4 |
| CS-CR-02 | Routes and handlers for Search and Filter | FR-5, FR-6 |
| CS-CR-03 | Student model covering all five confirmed fields | Confirmed data fields |
| CS-CR-04 | Views for Directory, Add Form, Edit Form | UI Design P-1 to P-3 |
| CS-CR-05 | Directory view displays all five confirmed fields | FR-2 |
| CS-CR-06 | Ability to route form submissions to persistence handlers | FR-1, FR-3 |

---

## 14. AI Recommendations Summary

| REC ID | Recommendation | Related Prior Recommendation |
| :--- | :--- | :--- |
| CS-REC-01 | Logical folder structure (routes/controllers/models/views/assets) | — |
| CS-REC-02 | Thin controllers with validation at the boundary | REC-02 (Functional Logic) |
| CS-REC-03 | Model-owned query construction for search/filter | — |
| CS-REC-04 | Progressive-enhancement JS for delete confirmation and client validation | REC-01, REC-02 |
| CS-REC-05 | `.env.example` + README setup documentation | Roadmap Phase 5 |
| CS-REC-06 | Optional API layer only if a decoupled stack is chosen | — |
| CS-REC-07 | Coding conventions for naming, validation, and error handling | — |

---

## 15. Web Builder Workflow & Next Steps

### 15.1 Workflow Position

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

### 15.2 Next Steps

1. **Review and approve this Coding Structure Document.**
2. **Resolve or formally defer the blocking Open Decisions**, at minimum:
   - OD-1 (technology stack) — blocks the entire scaffold.
   - OD-9 (database engine) — blocks migrations and DB config.
   - OD-6 (deletion strategy) — blocks the delete handler.
   - OD-2 (authentication) — determines whether auth routes/middleware exist.
   - OD-3 and OD-4 (search/filter scope) — block the directory query logic.
   - OD-5 (course input method) — blocks form and filter widgets.
   - OD-7 and OD-8 — block validation and pagination logic respectively.
3. **Begin implementation** using the approved scaffold once the blocking Open Decisions above are resolved through the governance flow.
4. **Update this document** if any Open Decision is resolved after approval, so the scaffold reflects the confirmed choice.

### 15.3 Governance Note

- This document does not convert any Open Decision into a Confirmed Decision.
- No new project stage, feature, or architecture layer has been introduced.
- All structural choices that depend on unresolved decisions are shown as alternatives and labeled AI Recommendations.

---

## Final Coding Structure Status

**Coding Structure Status:** Under Review — Pending Open Decision Resolution

The coding structure has been defined in a framework-agnostic form to remain consistent with the unresolved Open Decisions (particularly OD-1 and OD-9). The confirmed scope (FR-1 to FR-6 and the five student fields) is fully covered by the proposed routes, controllers, model, and views. All optional surfaces (delete confirmation, validation, pagination, authentication, API layer) are labeled as AI Recommendations or Open Decisions. No Open Decision has been silently resolved, and no new requirement has been introduced.

The project may proceed to **implementation** once this document is approved and the blocking Open Decisions are resolved or explicitly deferred through the governance flow defined in the Verification document.
✓ Approved & Locked Cancel
Stage Information
Coding Structure

Actual coding ke liye project ka technical structure define karna.
Expected Output

Pages, routes, controllers, folders, assets, JavaScript, CSS, APIs and coding structure.
Previous Stages
Project Understanding
✓ Available
Database Design
✓ Available
Functional Logic
✓ Available
UI Design
✓ Available
Verification
✓ 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.