Chapter: Preface

About This Textbook

This engineering textbook provides an exhaustive, source-verified technical reference for JoinTree (jointree.in), an institutional campus network and academic resource repository developed for Varadaraja Degree College (VDC), Tumkur, Karnataka, India.

Inspired by the pedagogical structure, visual clarity, and technical depth of AdaCore's classic programming monographs (such as Introduction to Ada), this book explains every major subsystem of the JoinTree platform. It covers theoretical botanical algorithms, full-stack Next.js 16 architecture, relational database engineering with Prisma and SQLite, role-based access control, in-browser PDF streaming, Progressive Web App adaptations, and end-to-end API specifications.

---

Pedagogical Structure & Visual Conventions

To make complex full-stack concepts accessible to both undergraduate students and senior academic evaluators, this book adopts strict visual conventions throughout its chapters:

1. Distinctive Callout Boxes

- Note (::: {.callout-note}): Highlights vital implementation details, institutional workflows, or background rationale. - Attention (::: {.callout-caution} or ::: {.callout-warning}): Identifies security barriers, data validation rules, or edge cases that must not be violated. - Hint (::: {.callout-tip}): Provides best practices, optimization techniques, or quick tips for viva examiners. - In Other Systems: Compares JoinTree's implementation decisions (e.g., custom Canvas 2D vector projection vs. WebGL/Three.js; Prisma ORM vs. raw SQL) with standard industry alternatives.

2. Formal Code Listings & Metadata

Every important code example is presented in a formal, numbered listing accompanied by code block metadata indicating its repository source path and deterministic hash:

// Example Listing
export interface Vec3 {
  x: number;
  y: number;
  z: number;
}

3. Verified Runtime Outputs

Where relevant, listings are immediately followed by actual console outputs or HTTP response payloads captured from the running software, demonstrating empirical proof of execution.

---

Reader Roadmap

- Part I: Foundations (Chapters 1–4): Institutional genesis, problem analysis, architectural topology, and complete repository source map. - Part II: Core Systems & Algorithms (Chapters 5–7): Relational database design (all 13 models), mathematical procedural L-System 3D tree engine, and authentication security. - Part III: Application Modules (Chapters 8–12): Academic Notes Hub, Official Bulletin Board, Member Directory, Admin Governance, and Progressive Web App adaptations. - Part IV: Reference & Defense (Chapters 13–17 & Appendices): End-to-end REST API catalogue, deployment, testing, BCA viva defense guide with 35 questions, glossary, and coverage audit.

Chapter: Executive Genesis & Institutional Mission

1.1 The Institutional Context: Varadaraja Degree College

Higher education institutions in regional academic centers such as Tumkur, Karnataka, face acute logistical hurdles in managing student communications, curriculum materials, and community engagement. Varadaraja Degree College (VDC) operates across multiple undergraduate streams:

1. Bachelor of Computer Applications (BCA): Focused on software development, database systems, networking, and computer architecture. 2. Bachelor of Business Administration (BBA): Centered on management, marketing, organizational behavior, and finance. 3. Bachelor of Commerce (B.Com): Emphasizing accounting, taxation, corporate law, and commercial operations.

Historically, academic notices were disseminated through physical cork bulletin boards pinned near administrative stairwells, or through ad-hoc, informal WhatsApp group chats created by students.

---

1.2 The Failure Modes of Informal Communication Channels

While informal mobile messaging applications (such as WhatsApp and Telegram) are convenient for peer-to-peer texting, they fail catastrophically as institutional communication channels. Four systemic failure modes plague collegiate environments:

1. The "Chat Avalanche" & Lost Notices

2. Ephemeral Academic Knowledge & Graduation Amnesia

3. Lack of Identity Verification & Privacy Hazards

4. Cross-Departmental Isolation

---

1.3 The JoinTree Solution: The Botanical Campus Metaphor

JoinTree (jointree.in) was engineered to solve these structural failures by mapping the collegiate ecosystem as a living botanical structure. Rather than presenting college data as an impersonal, sterile spreadsheet or bureaucratic portal, JoinTree models the institution as a growing tree rooted in theoretical computer science.

                  ┌──────────────────────────────┐
                  │   JOINTREE CAMPUS METAPHOR   │
                  └──────────────┬───────────────┘
                                 │
                     ┌───────────┴───────────┐
                     ▼                       ▼
            ┌─────────────────┐     ┌─────────────────┐
            │ Physical World  │     │ JoinTree Model  │
            ├─────────────────┤     ├─────────────────┤
            │ College Org     │ ──> │ Central Trunk   │
            │ Degree Programs │ ──> │ Major Branches  │
            │ Semesters/Years │ ──> │ Sub-branches    │
            │ Student Roster  │ ──> │ Foliage Leaves  │
            └─────────────────┘     └─────────────────┘

1. The Root & Trunk (VDC Administration): Represents the founding institution and administrative core. It anchors the platform and provides institutional stability. 2. The Primary Branches (Degree Courses): Each accredited degree program—BCA, BBA, B.Com—emerges from the central trunk as a primary limb with its own distinctive badge color and cohort year. 3. The Sub-Branches (Semesters & Batches): As academic programs advance through successive semesters, secondary boughs bifurcate organically. 4. The Foliage (Enrolled Students): Each student admitted to the institution blossoms as an interactive leaf. Clicking on a leaf reveals the student's verified roll number, name, department, and academic standing.

---

1.4 What JoinTree Is and What It Is Not

To establish clear technical boundaries during academic defense, the architecture explicitly defines the system's operational scope:

---

1.5 Stakeholder Impact Analysis

                    ┌────────────────────────────┐
                    │  JOINTREE STAKEHOLDERS     │
                    └─────────────┬──────────────┘
          ┌───────────────────────┼───────────────────────┐
          ▼                       ▼                       ▼
   ┌─────────────┐         ┌─────────────┐         ┌─────────────┐
   │  STUDENTS   │         │   FACULTY   │         │   ADMINS    │
   ├─────────────┤         ├─────────────┤         ├─────────────┤
   │ • Notes Hub │         │ • Bulletin  │         │ • ID Vetting│
   │ • 3D Leaves │         │ • Broadcasts│         │ • Audit Log │
   │ • Directory │         │ • Inquiries │         │ • Telemetry │
   └─────────────┘         └─────────────┘         └─────────────┘

- Students: Gain instant, authenticated access to semester-curated lecture notes and previous question papers with in-browser PDF previews. They receive broadcast circulars without WhatsApp noise. - Faculty & HODs: Broadcast verified announcements to targeted audiences (All, Students Only, Teachers Only) and resolve student inquiries in threaded discussion sections. - College Administrators: Audit all registrations, verify student ID cards before activation, maintain departmental rosters, and monitor client crash telemetry via automated bug tracking.

Chapter: System Requirements & Operational Scope

2.1 Functional Requirements Specification

The functional requirements of JoinTree specify the exact operations, workflows, and automated behaviors the software must deliver.

Table of Core Functional Requirements

---

2.2 Non-Functional Requirements (NFR)

The non-functional requirements define the software quality attributes, performance thresholds, and security benchmarks governing JoinTree:

1. Performance & Frame Rates

2. Security & Data Integrity

3. Portability & Hardware Independence

4. Reliability & Graceful Degradation

---

2.3 User Role & Access Control Matrix

JoinTree defines five access tiers. Each user account is assigned an enumerated role and an operational status:

┌────────────────────────────────────────────────────────────────────────┐
│                   JOINTREE ROLE-BASED ACCESS MATRIX                    │
│                                                                        │
│   Capabilities             Public   Pending   Student  Teacher  Admin  │
│   ──────────────────────   ──────   ───────   ───────  ───────  ─────  │
│   View Landing Page          ✓         ✓         ✓        ✓       ✓    │
│   Explore 3D Campus Tree     ✓         ✓         ✓        ✓       ✓    │
│   Browse Public Notes        ✓         ✓         ✓        ✓       ✓    │
│   Access Internal Notes      ✗         ✗         ✓        ✓       ✓    │
│   Upload Study Materials     ✗         ✗         ✓        ✓       ✓    │
│   View Official Notices      ✗         ✗         ✓        ✓       ✓    │
│   Post Comment Inquiries     ✗         ✗         ✓        ✓       ✓    │
│   Publish Announcements      ✗         ✗         ✗        ✓       ✓    │
│   Verify Student ID Badges   ✗         ✗         ✗        ✗       ✓    │
│   Manage Course Roster       ✗         ✗         ✗        ✗       ✓    │
│   Review Audit Logs          ✗         ✗         ✗        ✗       ✓    │
│   Review Bug Reports         ✗         ✗         ✗        ✗       ✓    │
└────────────────────────────────────────────────────────────────────────┘

---

2.4 Use Case Scenarios & Workflows

Use Case 1: Student Registration & ID Badge Verification

  [Unverified Student]                   [JoinTree Web App]                  [Administrator]
           │                                      │                                 │
           ├── 1. Submits Reg Form ──────────────>│                                 │
           │      (Name, Roll No, ID Card Image)  │                                 │
           │                                      ├── 2. Creates User in DB         │
           │                                      │      (Status: 'Pending')        │
           │<── 3. Redirected to /pending ────────┤                                 │
           │                                      │                                 │
           │                                      │<── 4. Opens Admin Approvals ────┤
           │                                      │       (/admin)                  │
           │                                      │─── 5. Displays ID Badge Photo ─>│
           │                                      │<── 6. Clicks "Approve" ─────────┤
           │                                      ├── 7. Updates Status: 'Active'   │
           │                                      │      Writes ModerationLog       │
           │<── 8. Full Access Granted ───────────┤                                 │

Use Case 2: In-Browser Academic Note Sharing & Inspection

  [BCA Student / Faculty]                [Next.js API Handler]             [SQLite Database]
           │                                      │                                 │
           ├── 1. Uploads PDF Note ──────────────>│                                 │
           │      (Title, Sem 5, Base64 Stream)   ├── 2. Validates File Size        │
           │                                      ├── 3. Persists Note Entity ─────>│
           │<── 4. Returns Success JSON ──────────┤                                 │
           │                                      │                                 │
           │  [Other Students Browse /notes]      │                                 │
           ├── 5. Filters by "Semester 5" ───────>│                                 │
           │                                      ├── 6. Queries Notes Table ──────>│
           │<── 7. Receives Note List ────────────┤                                 │
           ├── 8. Clicks "View PDF" ─────────────>│                                 │
           │<── 9. Streams Base64 to Iframe ──────┤                                 │

---

2.5 System Boundaries & Technical Constraints

1. Database Boundaries: The primary application datastore is SQLite 3 via Prisma ORM. While SQLite supports thousands of daily transactions for regional college campus intranets, highly concurrent write operations in large universities (> 50,000 active sessions) would necessitate migrating to PostgreSQL or MySQL. 2. File Payload Thresholds: Because uploaded study notes and ID card badges are encoded as base64 DataURLs directly in the database for atomic consistency, individual uploads are constrained to maximum file sizes of 5MB to 10MB to maintain optimal database query speeds. 3. PWA Offline Scope: The Service Worker pre-caches static application assets, icons, and shell layouts. Dynamic data (such as live announcements or newly added student leaves) requires active internet connectivity for real-time synchronization.

Chapter: System Architecture & Engineering Stack

3.1 Architectural Paradigm: Modern Full-Stack Monolith

JoinTree is architected as an integrated full-stack application built upon Next.js 16 (App Router) and React 19.

In conventional web development curricula, students are often taught multi-tiered architectures where the frontend (e.g., a React single-page app bundled with Vite) and the backend (e.g., an Express.js or Django REST API) live in separate repositories with distinct deployment lifecycles. JoinTree intentionally adopts a unified full-stack architecture:

┌────────────────────────────────────────────────────────────────────────┐
│                      JOINTREE FULL-STACK TOPOLOGY                      │
│                                                                        │
│   CLIENT LAYER                                                         │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ • Web Browsers (Chrome, Edge, Safari, Firefox)                 │   │
│   │ • Progressive Web App Shell & Service Worker Cache (sw.js)     │   │
│   │ • Native Platform Provider (Android Haptics & Windows Fluent)  │   │
│   └────────────────────────────────────────────────────────────────┘   │
│                                   │                                    │
│                                   ▼ HTTPS / Fetch API                  │
│   NEXT.JS 16 APPLICATION TIER (Node.js Server Runtime)                 │
│   ┌───────────────────────────────┬────────────────────────────────┐   │
│   │ React 19 Server Components    │ Next.js API Route Handlers     │   │
│   │ • SSR Initial Layouts         │ • /api/auth (Login, Register)  │   │
│   │ • Static Route Generation     │ • /api/notes (Document stream) │   │
│   │ • Fast Contentful Paint       │ • /api/admin (Approvals, Logs) │   │
│   └───────────────────────────────┴────────────────────────────────┘   │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ Client Component Islands ('use client')                        │   │
│   │ • Canvas 2D 3D-LSystem Engine (src/lib/tree-render.ts)         │   │
│   │ • PDF Viewer Modal & Interactive Feed Components               │   │
│   └────────────────────────────────────────────────────────────────┘   │
│                                   │                                    │
│                                   ▼ Type-Safe Query Engine             │
│   DATA PERSISTENCE LAYER                                               │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ • Prisma ORM 6.11.1 (Type-Safe Query Builder & Migrations)     │   │
│   │ • SQLite Database Engine (prisma/dev.db & /tmp runtime)        │   │
│   └────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘

Why Next.js 16 App Router?

---

3.2 The Technology Stack at a Glance

---

3.3 The Data Layer: SQLite & Prisma ORM

The primary persistence engine in JoinTree is SQLite 3, accessed exclusively through Prisma ORM 6.11.1.

The Singleton Design Pattern in src/lib/db.ts

To solve this, JoinTree implements the Singleton Design Pattern in src/lib/db.ts:

// Listing 3.1: src/lib/db.ts — Prisma Singleton
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['error', 'warn'] : ['error'],
  });

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

---

3.4 Hybrid Architecture Note: SQLite, Supabase, and Firebase

During the technical inspection of the repository, three distinct persistence mechanisms were discovered:

1. Active Primary Database: SQLite (prisma/dev.db managed by prisma/schema.prisma). All user-facing screens (/, /network, /notes, /announcements, /admin, /directory) read and write to this database. 2. Supabase Schema Migrations (supabase/): Contains historical PostgreSQL schema migrations (001_schema.sql, 002_rls_policies.sql, 003_seed_data.sql). Some secondary API routes include fallbacks to Supabase if configured. 3. Firebase Client Integration: The application includes client-side Firebase authentication tokens in src/lib/firebase.ts and server-side token verification in src/app/api/auth/firebase-login/route.ts to support OAuth logins.

Chapter: Repository Structure & Source Code Map

4.1 Complete Directory Inventory

The JoinTree codebase is organized into modular directories adhering to Next.js App Router and Prisma standards:

TreeLink/ (Repository Root)
├── .env / .env.local             # Environment variable declarations
├── AGENTS.md                     # Next.js 16 App Router agent conventions
├── package.json                  # Dependencies, scripts, and build metadata
├── tsconfig.json                 # TypeScript compiler configuration
├── next.config.ts                # Next.js bundler and cache configuration
├── prisma/                       # Database models and local database storage
│   ├── schema.prisma             # 13 Relational models (Active schema)
│   ├── dev.db                    # Primary SQLite database file
│   └── migrations/               # Database migration audit history
├── public/                       # Static public assets served at root
│   ├── manifest.json             # Web App Manifest for PWA installation
│   ├── sw.js                     # Custom Service Worker caching script
│   ├── icon.png                  # VDC JoinTree institutional crest
│   └── docs.html                 # Standalone printable manual
├── src/                          # Primary application source tree
│   ├── app/                      # Next.js 16 App Router pages and APIs
│   │   ├── layout.tsx            # Global HTML root layout
│   │   ├── page.tsx              # Public institutional landing page
│   │   ├── globals.css           # Global stylesheet and Tailwind 4 tokens
│   │   ├── network/page.tsx      # 3D interactive campus network tree
│   │   ├── notes/page.tsx        # Academic notes and PDF preview modal
│   │   ├── announcements/page.tsx# Official circular feed and discussions
│   │   ├── directory/page.tsx    # Searchable student and faculty index
│   │   ├── connect/page.tsx      # Campus Desk executive broadcasts
│   │   ├── admin/page.tsx        # Administrative control and ID vetting
│   │   ├── login/page.tsx        # Authentication and ID card registration
│   │   ├── pending/page.tsx      # ID card verification waiting room
│   │   ├── profile/page.tsx      # User profile editor
│   │   ├── offline/page.tsx      # PWA offline fallback page
│   │   ├── docs/page.tsx         # Integrated documentation route
│   │   ├── error.tsx             # Global React error boundary
│   │   ├── not-found.tsx         # HTTP 404 page handler
│   │   ├── robots.ts             # Search engine crawler permissions
│   │   ├── sitemap.ts            # Dynamic XML sitemap generator
│   │   └── api/                  # 18 RESTful Route Handlers
│   ├── components/               # Reusable UI, layout, and platform widgets
│   │   ├── native-platform-provider.tsx # Android haptics & Windows styling
│   │   ├── service-worker-register.tsx  # PWA service worker lifecycle
│   │   ├── mobile-bottom-nav.tsx        # Touch-friendly bottom navigation
│   │   └── android-install-prompt.tsx   # PWA home screen installation banner
│   └── lib/                      # Pure helper libraries and algorithms
│       ├── db.ts                 # Prisma Client Singleton with hot-reload guard
│       ├── lsystem.ts            # 3D Vector Math & L-System Grammar
│       ├── tree-render.ts        # Canvas 2D projection & raycasting
│       └── haptics.ts            # Navigator Vibration API wrappers
├── docs/                         # Architecture documentation and audits
├── docs-book/                    # Complete Quarto Book textbook sources
└── supabase/migrations/          # Secondary PostgreSQL schema history

---

4.2 Detailed Breakdown of Key Source Directories

1. src/app/ — Application Routes & Entrypoints

- src/app/page.tsx: The root public landing page. Renders the hero banner, live student statistics, degree program overviews, and student testimonials. - src/app/network/page.tsx: Renders the 3D procedural campus tree. Connects to src/lib/tree-render.ts and allows users to rotate the tree, click on student leaves, and inspect department branches. - src/app/notes/page.tsx: The academic resource library. Features multi-criteria filtering by semester (1 to 6) and department, with embedded base64 PDF modal previews. - src/app/announcements/page.tsx: The official bulletin board. Separates official circulars from casual chat and renders threaded comments beneath each post. - src/app/admin/page.tsx: The administrative governance portal. Displays pending student registrations, allows administrators to zoom into uploaded physical ID card photographs, and tracks audit logs.

2. src/lib/ — Core Algorithms & Infrastructure

3. src/components/ — Platform & UI Adapters

---

4.3 Excluded Directories & Development Artifacts

The following directories exist within the project root but are deliberately excluded from application deployment:

- node_modules/: Third-party npm dependencies installed locally. Never committed to version control. - .next/: Build cache and pre-rendered static artifacts generated by next build. - .turbo/: Turbopack incremental cache data. - tests/: Test specifications executed via test runners. - packages/shared/: Legacy workspace package preserved from earlier monorepo design iterations.

Chapter: Database Engineering & Persistence Layer

5.1 The 13 Relational Models in prisma/schema.prisma

JoinTree's relational schema is declared in prisma/schema.prisma and managed through Prisma ORM 6. Thirteen normalized models govern all persistent platform state.

┌────────────────────────────────────────────────────────────────────────┐
│                   JOINTREE ENTITY RELATIONSHIP DIAGRAM                 │
│                                                                        │
│   ┌──────────────┐ 1        * ┌──────────────┐                         │
│   │    Course    ├───────────<┤   Student    │ (Cascade Delete)        │
│   └──────────────┘            └──────────────┘                         │
│                                                                        │
│   ┌──────────────┐            ┌──────────────┐                         │
│   │     User     │            │     Note     │                         │
│   └──────────────┘            └──────────────┘                         │
│                                                                        │
│   ┌──────────────┐ 1        * ┌──────────────┐                         │
│   │ Announcement ├───────────<┤   Comment    │                         │
│   └──────────────┘            └──────────────┘                         │
│                                                                        │
│   ┌──────────────┐ 1        * ┌──────────────┐                         │
│   │DeletedAccount├───────────<┤AccountEnquiry│ (Cascade Delete)        │
│   └──────────────┘            └──────────────┘                         │
│                                                                        │
│   ┌──────────────┐            ┌──────────────┐                         │
│   │  Department  │            │  RollNumber  │                         │
│   └──────────────┘            └──────────────┘                         │
│                                                                        │
│   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                   │
│   │ModerationLog │ │  BugReport   │ │  SiteConfig  │                   │
│   └──────────────┘ └──────────────┘ └──────────────┘                   │
└────────────────────────────────────────────────────────────────────────┘

---

5.2 Model-by-Model Technical Dissection

1. Model: Course (Academic Program Branches)

model Course {
  id         String    @id @default(cuid())
  name       String    // e.g. "BCA 2024-25"
  batchYear  Int       // Academic cohort year (e.g. 2024)
  color      String    @default("#2e6fd1") // Hex color for 3D branch & badge
  order      Int       @default(0) // Visual ordering index
  department String    @default("General") // Department wing
  createdAt  DateTime  @default(now())
  students   Student[] // 1-to-Many relation with Student
}

2. Model: Student (Foliage Leaves)

model Student {
  id        String   @id @default(cuid())
  name      String
  rollNo    String   @unique // Official university registration number
  role      String   @default("Student")
  status    String   @default("Active") // Active | Inactive
  isSample  Boolean  @default(false) // True if created via quick +/- demo controls
  courseId  String
  course    Course   @relation(fields: [courseId], references: [id], onDelete: Cascade)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

@@index([courseId]) // B-Tree index for O(log N) leaf lookups
}

3. Model: User (Authentication & Identity)

model User {
  id         String   @id @default(cuid())
  name       String
  email      String   @unique
  password   String   // SHA-256 cryptographic hexadecimal digest
  role       String   @default("Student") // Student | Teacher | Director | Admin
  status     String   @default("Active")  // Active | Pending | Rejected | Inactive
  rollNumber String?  // Optional roll number link
  department String?  // Department affiliation
  joinYear   Int?     // Enrollment year
  bio        String?  // Profile biography
  avatar     String?  // Base64 DataURL profile picture
  hideEmail  Boolean  @default(false) // Privacy flag for directory
  idCard     String?  // Base64 DataURL uploaded physical college ID card badge
  createdAt  DateTime @default(now())
}

4. Model: Department & RollNumber

5. Model: Note (Academic Study Materials)

model Note {
  id           String   @id @default(cuid())
  title        String
  course       String   // Associated course name
  department   String   @default("General")
  semester     Int      @default(1) // Semester number (1 to 6)
  visibility   String   @default("Internal") // Internal (login required) | Public
  fileType     String   @default("pdf") // pdf | img | doc
  fileName     String?
  fileData     String?  // Base64 DataURL document stream for in-browser preview
  uploaderId   String
  uploaderName String
  createdAt    DateTime @default(now())
}

6. Models: Announcement & Comment (Official Bulletin)

7. Governance Models: ModerationLog, DeletedAccount, AccountEnquiry, BugReport, SiteConfig

---

5.3 The Database Engine: SQLite & Runtime Path Resolution

JoinTree uses SQLite 3 via the local file prisma/dev.db.

Runtime Path Management in src/lib/db.ts

// Excerpt from src/lib/db.ts
const dbPath = process.env.NODE_ENV === 'production'
  ? '/tmp/custom.db'
  : path.join(process.cwd(), 'prisma', 'dev.db');

Chapter: The 3D Procedural Tree Engine & Graphics Pipeline

6.1 Theoretical Foundations: Algorithmic Botany

JoinTree's flagship feature is its procedural 3D campus network tree. Rather than downloading heavy, static 3D polygons or relying on external game engines, the tree is mathematically generated in the user's browser using Lindenmayer Systems (L-Systems).

The theoretical framework derives from the groundbreaking research of Aristid Lindenmayer (1968) and the computer graphics formalisms developed by Prof. Przemyslaw Prusinkiewicz et al. at the University of Calgary (Modeling plant development with L-systems, 2018; The Algorithmic Beauty of Plants, 1990).

                      ┌────────────────────────────────────────┐
                      │    L-SYSTEM REWRITING IN THREE STEPS   │
                      └──────────────────┬─────────────────────┘
                                         │
               Step 1: Axiom ω (Trunk Seed)
               ω = F
                                         │
                                         ▼
               Step 2: Parallel Production Rule
               p: F ──> F [ + F ] [ - F ] F
                                         │
                                         ▼
               Step 3: Recursive Derivations
               n = 0: F                                 (Trunk Base)
               n = 1: F [ + F ] [ - F ] F               (Primary Branches)
               n = 2: F [ + F [ + F ] ... ]             (Secondary Twigs)
               n = D: Terminal Apices                   (Student Leaves)

---

6.2 The Three Mathematical Principles of the Tree Engine

1. Rodrigues' 3D Rotation Formula

$$\vec{v}_{\text{rot}} = \vec{v}\cos\theta + (\vec{k} \times \vec{v})\sin\theta + \vec{k}(\vec{k} \cdot \vec{v})(1 - \cos\theta)$$

// Listing 6.1: Rodrigues Rotation in src/lib/lsystem.ts
const rot = (v: Vec3, k: Vec3, rad: number): Vec3 => {
  const c = Math.cos(rad);
  const s = Math.sin(rad);
  return add(add(scl(v, c), scl(crs(k, v), s)), scl(k, dot(k, v) * (1 - c)));
};

2. Leonardo da Vinci & Shinozaki Pipe Model Theory

$$d_0^\eta = \sum_{i=1}^k d_i^\eta \implies w = \left(\sum w_i\right)^{1/\eta}$$

In src/lib/lsystem.ts, JoinTree sets exponent \(\eta = 2.5\) (eta: 2.5) and initial base width \(w_0 = 0.85\). This produces organic tapering: broad and sturdy at the college trunk, tapering naturally to student leaves.

3. Mulberry32 Deterministic PRNG

// Listing 6.2: Mulberry32 PRNG in src/lib/lsystem.ts
function mulberry32(seed: number) {
  let a = seed >>> 0;
  return () => {
    a |= 0;
    a = (a + 0x6d2b79f5) | 0;
    let t = Math.imul(a ^ (a >>> 15), 1 | a);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

---

6.3 The 2D Canvas Projection & Raycasting Engine

The visual representation of the tree is computed in src/lib/tree-render.ts.

1. Orthographic Turntable Camera Projection

$$x' = x\cos\phi + z\sin\phi, \quad z' = -x\sin\phi + z\cos\phi$$ $$y' = -(y\cos\theta - z'\sin\theta)$$

// Listing 6.3: src/lib/tree-render.ts — Projection Implementation
export function projectTree(tree: Tree, yawDeg: number, pitchDeg: number, out?: Projected): Projected {
  const cy = Math.cos((yawDeg * Math.PI) / 180);
  const sy = Math.sin((yawDeg * Math.PI) / 180);
  const cp = Math.cos((pitchDeg * Math.PI) / 180);
  const sp = Math.sin((pitchDeg * Math.PI) / 180);

for (let i = 0; i < segCount; i++) {
    const s = tree.segments[i];
    const ax = s.a.x  cy + s.a.z  sy;
    const az = -s.a.x  sy + s.a.z  cy;
    const ay = -(s.a.y  cp - az  sp);
    const bx = s.b.x  cy + s.b.z  sy;
    const bz = -s.b.x  sy + s.b.z  cy;
    const by = -(s.b.y  cp - bz  sp);

const o = i * 6;
    proj.seg[o] = ax;
    proj.seg[o + 1] = ay;
    proj.seg[o + 2] = bx;
    proj.seg[o + 3] = by;
    proj.seg[o + 4] = s.w;
    proj.seg[o + 5] = s.d;
  }
  return proj;
}

2. Zero-Allocation Typed Array Buffers

3. Mouse Raycasting Hit Detection

Chapter: Authentication, Authorization & Security

7.1 Identity Model & Account States

User accounts in JoinTree are represented by the User model in prisma/schema.prisma. Every user account is governed by two state fields: 1. role: Student | Teacher | Director | Admin 2. status: Active | Pending | Rejected | Inactive

┌────────────────────────────────────────────────────────────────────────┐
│                     USER ACCOUNT LIFECYCLE STATES                      │
│                                                                        │
│               [Registration Form at /login]                            │
│                             │                                          │
│                             ▼                                          │
│                    ┌─────────────────┐                                 │
│                    │     Pending     │ (Quarantine: Restricts to       │
│                    └────────┬────────┘  the /pending waiting room)     │
│                             │                                          │
│                ┌────────────┴────────────┐                             │
│                ▼                         ▼                             │
│       [Admin Approves]          [Admin Rejects]                        │
│                │                         │                             │
│                ▼                         ▼                             │
│       ┌─────────────────┐       ┌─────────────────┐                    │
│       │     Active      │       │    Rejected     │                    │
│       │ (Full Access)   │       │ (Access Denied) │                    │
│       └─────────────────┘       └─────────────────┘                    │
└────────────────────────────────────────────────────────────────────────┘

---

7.2 The Student Registration & ID Badge Upload Workflow

To prevent unauthorized individuals from entering the platform, registration requires three layers of institutional verification:

1. Roster Match: The candidate's registration roll number must match a valid pre-seeded record in the RollNumber table. 2. Badge Photography: The student must capture and upload a photograph of their physical college ID card badge. The image is parsed into a base64 DataURL and stored in User.idCard. 3. Pending Quarantine: The newly registered account is set to status: "Pending". A Next.js route guard intercepts pending accounts, restricting them to /pending until an administrator manually inspects the ID badge in /admin.

// Listing 7.1: src/app/api/auth/register/route.ts — Registration Handler
import { NextResponse } from 'next/server';
import { prisma } from '@/lib/db';
import crypto from 'crypto';

export async function POST(req: Request) {
  const { name, email, password, rollNumber, department, idCard } = await req.json();

// 1. Verify uniqueness
  const existing = await prisma.user.findUnique({ where: { email } });
  if (existing) {
    return NextResponse.json({ error: 'Email already registered' }, { status: 400 });
  }

// 2. Cryptographic SHA-256 password hash
  const hashedPassword = crypto.createHash('sha256').update(password).digest('hex');

// 3. Persist record in Pending status
  const user = await prisma.user.create({
    data: {
      name,
      email,
      password: hashedPassword,
      rollNumber,
      department,
      idCard, // Base64 DataURL of physical ID card badge
      role: 'Student',
      status: 'Pending', // Enforces administrative moderation queue
    },
  });

return NextResponse.json({ success: true, userId: user.id, status: user.status });
}

---

7.3 Cryptographic Password Security

Plaintext passwords are never stored in the database. In src/app/api/auth/register/route.ts and login/route.ts, incoming passwords are converted into 256-bit hexadecimal digests using the SHA-256 cryptographic hashing algorithm:

// Listing 7.2: Password Verification in src/app/api/auth/login/route.ts
const hash = crypto.createHash('sha256').update(password).digest('hex');
if (user.password !== hash) {
  return NextResponse.json({ error: 'Invalid email or password' }, { status: 401 });
}

---

7.4 Defense-in-Depth Security Controls

JoinTree implements multi-layered security protections:

1. SQL Injection Immunization: All queries execute via Prisma ORM methods (prisma.user.findUnique(), prisma.note.findMany()). User input is automatically escaped and treated strictly as parameter values rather than executable SQL statements. 2. Cross-Site Scripting (XSS) Prevention: React 19's virtual DOM automatically escapes untrusted strings before rendering them to HTML, preventing malicious JavaScript injection. 3. Email Privacy Toggling (hideEmail): Students can toggle hideEmail: true in their profile. When enabled, directory queries and public leaf popups mask the student's email address to protect their personal contact information.

Chapter: Academic Resource Hub & Document Streaming

8.1 Purpose & Academic Significance

The Academic Resource Hub located at /notes acts as the institutional repository for syllabus documentation, lecture notes, laboratory manuals, and previous years' university examination papers.

In conventional university portals, notes are either locked behind cumbersome ERP systems that require students to log in on desktop computers, or scattered across personal Google Drive folders that break after semester transitions. JoinTree provides a unified, mobile-first document library with immediate in-browser previews.

┌────────────────────────────────────────────────────────────────────────┐
│                   ACADEMIC NOTES REPOSITORY MATRIX                     │
│                                                                        │
│                Semester 1   Semester 2   Semester 3 ... Semester 6     │
│   BCA Stream   [Notes PDF]  [Lab Code]   [Question]     [Project Docs] │
│   BBA Stream   [Marketing]  [Economics]  [Finance]      [HR Reports]   │
│   B.Com Stream [Accounts]   [Taxation]   [Auditing]     [GST Law]      │
└────────────────────────────────────────────────────────────────────────┘

---

8.2 In-Browser Base64 Document Streaming

A major friction point for students studying on budget smartphones is the requirement to download heavy 10MB PDF files into their local phone storage every time they want to read an exam formula or question paper.

JoinTree implements In-Browser Base64 Document Streaming: 1. When notes are uploaded, the file stream is encoded as a base64 DataURL: data:application/pdf;base64,JVBERi0xLjQK.... 2. The data stream is stored in the fileData field of the Note table. 3. When a student clicks "View", the client renders an embedded modal containing an HTML5