Repository docs from .qoder/repowiki

Institutional Organization

Referenced Files in This Document

• CollegePage.tsx
• BranchPage.tsx
• CollegeRequestTable.tsx
• CollegeTable.tsx
• CollegeForm.tsx
• College.ts
• CollegeRequest.ts
• http.ts
• college.controller.ts
• college.route.ts
• college.service.ts
• college.schema.ts
• college.types.ts
• college.adapter.ts
• college-branch.table.ts
• branch.table.ts
• branch.service.ts
• branch.controller.ts
• branch.schema.ts
• 0001_flat_mathemanic.sql
• 0002_perfect_drax.sql

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document describes the institutional organization management capabilities in the admin dashboard. It covers the college administration interface, branch management systems, and institutional hierarchy controls. It also documents the college approval workflows, branch creation processes, institutional relationship management, integration with institutional APIs, data validation processes, and administrative oversight tools. Examples of college onboarding, branch configuration, and institutional governance workflows are included to guide administrators through typical tasks.

Project Structure

The institutional organization management spans the admin frontend and the server backend:

• Admin frontend pages and components manage college and branch records, display requests, and orchestrate approval workflows.
• Server backend exposes REST endpoints for colleges and branches, enforces validation, and manages institutional relationships.

graph TB
subgraph "Admin Frontend"
CP["CollegePage.tsx"]
BP["BranchPage.tsx"]
CRT["CollegeRequestTable.tsx"]
CT["CollegeTable.tsx"]
CF["CollegeForm.tsx"]
HT["http.ts"]
end
subgraph "Server Backend"
RC["college.route.ts"]
CC["college.controller.ts"]
CS["college.service.ts"]
CA["college.adapter.ts"]
BS["branch.service.ts"]
BC["branch.controller.ts"]
BT["branch.table.ts"]
CB["college-branch.table.ts"]
end
CP --> HT
BP --> HT
CRT --> HT
CT --> HT
CF --> HT
HT --> RC
RC --> CC
CC --> CS
CS --> CA
CS --> CB
CS --> BT
RC --> BC
BC --> BS

Diagram sources

• CollegePage.tsx
• BranchPage.tsx
• CollegeRequestTable.tsx
• CollegeTable.tsx
• CollegeForm.tsx
• http.ts
• college.route.ts
• college.controller.ts
• college.service.ts
• college.adapter.ts
• branch.service.ts
• branch.controller.ts
• branch.table.ts
• college-branch.table.ts

Section sources

• CollegePage.tsx
• BranchPage.tsx
• college.route.ts
• branch.controller.ts

Core Components

• Admin Pages
  • CollegePage: Lists colleges and displays pending college requests; supports creating colleges and approving/rejecting requests.
  • BranchPage: Manages branch catalog (create, delete) and displays current branches.
• Admin Components
  • CollegeTable: Displays college records with editable actions.
  • CollegeRequestTable: Shows pending requests and allows approval (with inline form) or rejection.
  • CollegeForm: Handles creation and editing of colleges, including profile image upload and branch selection.
• Types
  • College and CollegeRequest define the data contracts used by the admin UI.
• HTTP Client
  • http.ts and rootHttp.ts provide base URLs and interceptors for API communication.

Key responsibilities:

• Admin UI orchestrates CRUD operations and approval workflows.
• Server validates inputs, enforces uniqueness and domain checks, and maintains institutional relationships.

Section sources

• CollegePage.tsx
• BranchPage.tsx
• CollegeRequestTable.tsx
• CollegeTable.tsx
• CollegeForm.tsx
• College.ts
• CollegeRequest.ts
• http.ts

Architecture Overview

The admin dashboard integrates with the server backend through typed HTTP clients. The backend enforces validation, manages institutional relationships, and records audit events.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "HTTP Client"
participant Route as "college.route.ts"
participant Ctrl as "college.controller.ts"
participant Svc as "college.service.ts"
participant Repo as "college.adapter.ts"
participant DB as "DB"
Admin->>HTTP : "GET /colleges/get/all"
HTTP->>Route : "GET /colleges"
Route->>Ctrl : "getColleges(query)"
Ctrl->>Svc : "getColleges(filters)"
Svc->>Repo : "CachedRead.findAll(filters)"
Repo->>DB : "SELECT colleges"
DB-->>Repo : "colleges"
Repo-->>Svc : "colleges"
Svc-->>Ctrl : "colleges"
Ctrl-->>HTTP : "200 OK {colleges, count}"
HTTP-->>Admin : "colleges"

Diagram sources

• college.route.ts
• college.controller.ts
• college.service.ts
• college.adapter.ts
• http.ts

Detailed Component Analysis

College Administration Interface

The CollegePage aggregates two primary views:

• Colleges list with edit actions.
• Pending college requests with approval/rejection actions.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "HTTP Client"
participant Route as "college.route.ts"
participant Ctrl as "college.controller.ts"
participant Svc as "college.service.ts"
Admin->>HTTP : "GET /colleges/get/all"
HTTP->>Route : "GET /colleges"
Route->>Ctrl : "getColleges(query)"
Ctrl->>Svc : "getColleges(filters)"
Svc-->>Ctrl : "colleges"
Ctrl-->>HTTP : "200 OK {colleges, count}"
HTTP-->>Admin : "colleges"
Admin->>HTTP : "GET /college-requests"
HTTP->>Route : "GET /colleges/requests"
Route->>Ctrl : "getCollegeRequests()"
Ctrl->>Svc : "getCollegeRequests()"
Svc-->>Ctrl : "requests"
Ctrl-->>HTTP : "200 OK {requests}"
HTTP-->>Admin : "requests"

Diagram sources

• CollegePage.tsx
• college.route.ts
• college.controller.ts
• college.service.ts

Section sources

• CollegePage.tsx
• college.controller.ts
• college.service.ts

Branch Management Systems

BranchPage provides:

• Listing all branches.
• Creating new branches with name and code.
• Deleting branches.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "HTTP Client"
participant BR as "branch.controller.ts"
participant BS as "branch.service.ts"
participant DB as "DB"
Admin->>HTTP : "POST /branches/create {name, code}"
HTTP->>BR : "createBranch(body)"
BR->>BS : "createBranch(data)"
BS->>DB : "INSERT branches"
DB-->>BS : "newBranch"
BS-->>BR : "newBranch"
BR-->>HTTP : "201 Created branch"
HTTP-->>Admin : "branch"

Diagram sources

• BranchPage.tsx
• branch.controller.ts
• branch.service.ts

Section sources

• BranchPage.tsx
• branch.controller.ts
• branch.service.ts

Institutional Hierarchy Controls

Institutional hierarchy is modeled via a many-to-many relationship between colleges and branches:

• A college can have multiple branches.
• A branch can be associated with multiple colleges.
• The join table tracks these associations and ensures uniqueness per college-branch pair.

erDiagram
COLLEGES {
uuid id PK
text name
text email_domain
text city
text state
text profile
timestamptz created_at
timestamptz updated_at
}
BRANCHES {
uuid id PK
text name
text code
timestamptz created_at
timestamptz updated_at
}
COLLEGE_BRANCHES {
uuid id PK
uuid college_id FK
uuid branch_id FK
timestamptz created_at
}
COLLEGES ||--o{ COLLEGE_BRANCHES : "has"
BRANCHES ||--o{ COLLEGE_BRANCHES : "has"

Diagram sources

• college-branch.table.ts
• branch.table.ts
• 0001_flat_mathemanic.sql
• 0002_perfect_drax.sql

Section sources

• college-branch.table.ts
• branch.table.ts
• 0001_flat_mathemanic.sql
• 0002_perfect_drax.sql

College Approval Workflows

Pending college requests are reviewed and resolved by:

• Approving a request and creating a college from the request details.
• Rejecting a request and closing it.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "HTTP Client"
participant Route as "college.route.ts"
participant Ctrl as "college.controller.ts"
participant Svc as "college.service.ts"
Admin->>HTTP : "PATCH /college-requests/ : id {status, resolvedCollegeId?}"
HTTP->>Route : "PATCH /colleges/requests/ : id"
Route->>Ctrl : "updateCollegeRequest(params, body)"
Ctrl->>Svc : "updateCollegeRequest(id, updates)"
Svc-->>Ctrl : "updatedRequest"
Ctrl-->>HTTP : "200 OK {request}"
HTTP-->>Admin : "updatedRequest"

Diagram sources

• CollegeRequestTable.tsx
• college.route.ts
• college.controller.ts
• college.service.ts

Section sources

• CollegeRequestTable.tsx
• college.controller.ts
• college.service.ts

Branch Creation Processes

Branch creation is validated and persisted:

• Validation ensures minimum length for name and code.
• Creation inserts a new branch record.

flowchart TD
Start(["Create Branch"]) --> Validate["Validate name and code"]
Validate --> Valid{"Valid?"}
Valid --> |No| Error["Return validation error"]
Valid --> |Yes| Insert["Insert branch into DB"]
Insert --> Success["Return created branch"]
Error --> End(["End"])
Success --> End

Diagram sources

• branch.schema.ts
• branch.controller.ts
• branch.service.ts

Section sources

• BranchPage.tsx
• branch.schema.ts
• branch.service.ts

Institutional Relationship Management

Relationships between colleges and branches are managed via:

• Setting branches for a college during creation or update.
• Fetching branches associated with a college.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "HTTP Client"
participant Route as "college.route.ts"
participant Ctrl as "college.controller.ts"
participant Svc as "college.service.ts"
participant Repo as "college.adapter.ts"
participant DB as "DB"
Admin->>HTTP : "GET /colleges/ : id/branches"
HTTP->>Route : "GET /colleges/ : id/branches"
Route->>Ctrl : "getCollegeBranches(params)"
Ctrl->>Svc : "getCollegeBranches(id)"
Svc->>Repo : "findBranchesByCollegeId(id)"
Repo->>DB : "SELECT join records"
DB-->>Repo : "branch ids"
Repo-->>Svc : "branch ids"
Svc-->>Ctrl : "branches"
Ctrl-->>HTTP : "200 OK {branches}"
HTTP-->>Admin : "branches"

Diagram sources

• college.controller.ts
• college.service.ts
• college.adapter.ts

Section sources

• college.controller.ts
• college.service.ts
• college.adapter.ts

Integration with Institutional APIs

The admin client communicates with backend endpoints using a shared HTTP client:

• Base URLs are derived from environment variables.
• Interceptors normalize responses and attach bearer tokens.

sequenceDiagram
participant Admin as "Admin UI"
participant HTTP as "http.ts"
participant API as "Backend API"
Admin->>HTTP : "POST /colleges/create"
HTTP->>API : "POST /colleges"
API-->>HTTP : "201 Created {college}"
HTTP-->>Admin : "college"

Diagram sources

• http.ts
• college.route.ts

Section sources

• http.ts
• college.route.ts

Data Validation Processes

Validation is enforced at the server boundary:

• College creation and update validate presence and format of fields.
• College request creation validates email domain format and requester domain alignment.
• Branch creation validates name and code lengths.

flowchart TD
Start(["Validate Request"]) --> Schema["Apply Zod schema"]
Schema --> DomainCheck{"Email domain check?"}
DomainCheck --> |Yes| RequesterDomain["Verify requester domain matches email domain"]
DomainCheck --> |No| Proceed["Proceed to service"]
RequesterDomain --> Valid{"Valid?"}
Valid --> |No| Error["Throw validation error"]
Valid --> |Yes| Proceed
Proceed --> End(["Pass to service"])
Error --> End

Diagram sources

• college.schema.ts
• branch.schema.ts

Section sources

• college.schema.ts
• branch.schema.ts

Administrative Oversight Tools

Administrative actions are audited:

• Actions like creating, updating, and deleting colleges are recorded with before/after snapshots and metadata.

sequenceDiagram
participant Svc as "college.service.ts"
participant Audit as "Audit Logger"
participant DB as "DB"
Svc->>Audit : "recordAudit({ action, entityType, entityId, before?, after?, metadata })"
Audit->>DB : "INSERT audit log"
DB-->>Audit : "ok"
Audit-->>Svc : "ok"

Diagram sources

• college.service.ts
• college.service.ts

Section sources

• college.service.ts
• college.service.ts

Dependency Analysis

The admin components depend on the HTTP client and share types with the backend. The server enforces validation and persists data through adapters and tables.

graph LR
CF["CollegeForm.tsx"] --> T1["College.ts"]
CT["CollegeTable.tsx"] --> T1
CRT["CollegeRequestTable.tsx"] --> T2["CollegeRequest.ts"]
CP["CollegePage.tsx"] --> CF
CP --> CT
CP --> CRT
BP["BranchPage.tsx"] --> HTTP["http.ts"]
HTTP --> RC["college.route.ts"]
HTTP --> BR["branch.controller.ts"]
RC --> CC["college.controller.ts"]
BR --> BC["branch.controller.ts"]
CC --> CS["college.service.ts"]
BC --> BS["branch.service.ts"]
CS --> CA["college.adapter.ts"]
CS --> CB["college-branch.table.ts"]
CS --> BT["branch.table.ts"]

Diagram sources

• CollegeForm.tsx
• CollegeTable.tsx
• CollegeRequestTable.tsx
• CollegePage.tsx
• BranchPage.tsx
• College.ts
• CollegeRequest.ts
• http.ts
• college.route.ts
• branch.controller.ts
• college.controller.ts
• college.service.ts
• college.adapter.ts
• college-branch.table.ts
• branch.table.ts

Section sources

• CollegeForm.tsx
• CollegeTable.tsx
• CollegeRequestTable.tsx
• CollegePage.tsx
• BranchPage.tsx
• college.route.ts
• branch.controller.ts

Performance Considerations

• Batch fetching: CollegePage fetches colleges and requests concurrently to reduce latency.
• Caching: Services utilize cached reads for colleges and branches to minimize database load.
• Indexes: Branch tables include indexes on name and code to speed up lookups.
• Unique constraints: The join table ensures unique college-branch pairs to prevent duplicates.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

• Validation errors on creation/edit:
  • Verify required fields and formats (e.g., email domain, name/code lengths).
  • See validation schemas for precise constraints.
• Conflict on email domain:
  • Ensure the email domain is unique; conflicts raise a conflict error.
• Requester domain mismatch:
  • The requester’s email must belong to the same domain as the requested email domain.
• Branch operations:
  • Ensure name and code meet minimum length requirements.
  • Confirm branch deletion does not violate referential integrity if used by colleges.

Section sources

• college.schema.ts
• branch.schema.ts
• college.service.ts
• college.service.ts

Conclusion

The admin dashboard provides a comprehensive toolkit for managing institutional organizations:

• Colleges and branches are managed through dedicated pages and forms.
• Approval workflows streamline onboarding of new colleges from requests.
• Institutional relationships are modeled with a robust many-to-many schema.
• Validation and auditing ensure data integrity and transparency.
• The HTTP client and route/controller/service layers provide a clean separation of concerns and reliable integration points.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Example Workflows

• College Onboarding from Request
  • Review pending request in the “College requests” section.
  • Approve the request; the system opens a form pre-filled with request data.
  • Save the form to create the college and mark the request as approved with resolution metadata.
• Branch Configuration
  • Navigate to the “Branches” page.
  • Use the “Create Branch” dialog to add a new branch with a unique name and code.
  • Assign branches to colleges during college creation or update.
• Institutional Governance
  • Use the “Colleges” table to edit college details and manage branch assignments.
  • Monitor audit logs for administrative actions performed on colleges.

Section sources

• CollegeRequestTable.tsx
• CollegeForm.tsx
• BranchPage.tsx
• CollegeTable.tsx
• college.service.ts