Skip to content

User Directory System

Jump to bottom
github-actions[bot] edited this page Apr 24, 2026 · 2 revisions

User Directory System

**Referenced Files in This Document** - [student-directory.tsx](file://client/src/pages/student-directory.tsx) - [routes.ts](file://server/routes.ts) - [schema.ts](file://shared/schema.ts) - [storage.ts](file://server/storage.ts) - [admin-dashboard.tsx](file://client/src/pages/admin-dashboard.tsx) - [utils.ts](file://client/src/lib/utils.ts) - [config.ts](file://client/src/config.ts) - [db.ts](file://server/db.ts)

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

Introduction

This document describes the User Directory System, focusing on the student directory functionality with grade-level organization, search capabilities, filtering, and display mechanisms. It explains how user listings are presented, how contact information is managed, and how directory navigation works. It also covers search algorithms, sorting mechanisms, pagination, grade-level grouping, class organization, user relationship mapping, privacy controls, bulk operations, and administrative user management features.

Project Structure

The User Directory System spans the client-side React application and the server-side Express API with MongoDB storage. The key areas involved are:

  • Frontend: Student directory page with search, filters, tabs, and student cards
  • Backend: Routes for authentication and user management, storage layer for data access, and shared schemas for validation
  • Shared: Type-safe schemas for user data and validation rules
graph TB
subgraph "Client"
SD["Student Directory Page<br/>(student-directory.tsx)"]
AD["Admin Dashboard<br/>(admin-dashboard.tsx)"]
UT["Utilities<br/>(utils.ts)"]
CFG["Config<br/>(config.ts)"]
end
subgraph "Server"
RT["Routes<br/>(routes.ts)"]
ST["Storage Layer<br/>(storage.ts)"]
DB["MongoDB Connection<br/>(db.ts)"]
end
subgraph "Shared"
SC["Schemas<br/>(schema.ts)"]
end
SD --> RT
AD --> RT
RT --> ST
ST --> DB
SD --> UT
SD --> CFG
RT --> SC
ST --> SC
Loading

Diagram sources

  • student-directory.tsx
  • routes.ts
  • storage.ts
  • schema.ts
  • db.ts
  • admin-dashboard.tsx
  • utils.ts
  • config.ts

Section sources

  • student-directory.tsx
  • routes.ts
  • storage.ts
  • schema.ts
  • db.ts
  • admin-dashboard.tsx
  • utils.ts
  • config.ts

Core Components

  • Student Directory Page: Implements search, filters, grade grouping, and display of student cards with avatar, badges, and class/section metadata.
  • Backend Routes: Provide authentication, user retrieval, and workspace/channel messaging APIs (used for user relationships and communication).
  • Storage Layer: Manages user CRUD operations, class-based queries, and workspace membership.
  • Shared Schemas: Define user model, validation rules, and types for type safety.
  • Utilities: Provide helper functions like initials extraction for avatars.
  • Admin Dashboard: Provides administrative UI scaffolding for user management, classes, reports, and settings.

Section sources

  • student-directory.tsx
  • routes.ts
  • storage.ts
  • schema.ts
  • utils.ts
  • admin-dashboard.tsx

Architecture Overview

The system follows a layered architecture:

  • Presentation Layer: React components render the student directory and admin dashboard.
  • Application Layer: Express routes handle requests, enforce authentication/authorization, and delegate to the storage layer.
  • Data Access Layer: MongoDB-backed storage provides user and workspace operations.
  • Shared Contracts: Zod schemas define data contracts and validation.
sequenceDiagram
participant Browser as "Browser"
participant Client as "Student Directory Page"
participant API as "Express Routes"
participant Store as "Storage Layer"
participant Mongo as "MongoDB"
Browser->>Client : Load student directory
Client->>API : GET /api/students (mocked)
API->>Store : Retrieve users (placeholder)
Store->>Mongo : Query users
Mongo-->>Store : User documents
Store-->>API : User array
API-->>Client : JSON response (mock)
Client-->>Browser : Render filtered student grid
Loading

Diagram sources

  • student-directory.tsx
  • routes.ts
  • storage.ts
  • db.ts

Detailed Component Analysis

Student Directory Page

The student directory page provides:

  • Search: Case-insensitive search across name, city, and state.
  • Filters: Standard selection, state checkboxes, and grade group toggles.
  • Tabs: Group students by grade categories (Pre-Primary, Primary, Middle, Secondary, Senior Secondary).
  • Display: Grid of student cards with avatar, profile link, city/state badges, class, and optional section.
flowchart TD
Start([Render Student Directory]) --> LoadData["Load Students<br/>(mocked)"]
LoadData --> BuildFilters["Build Filters<br/>(search, standard, state, group)"]
BuildFilters --> ApplySearch["Apply Search Filter<br/>(name/city/state)"]
ApplySearch --> ApplyStandard["Apply Standard Filter"]
ApplyStandard --> ApplyState["Apply State Filter"]
ApplyState --> ApplyGroup["Apply Group Filter"]
ApplyGroup --> RenderGrid["Render Student Grid"]
RenderGrid --> End([Display Cards])
Loading

Diagram sources

  • student-directory.tsx
  • student-directory.tsx

Section sources

  • student-directory.tsx

Search and Filtering Logic

  • Search Algorithm: Linear scan with case-insensitive substring checks on name, city, and state.
  • Sorting: States are extracted and sorted alphabetically for filter options.
  • Filtering Options:
    • Standard: Single-select dropdown for individual grades.
    • State: Multi-select via dropdown menu checkboxes.
    • Group: Pre-defined grade groups mapped to sets of standards.
  • Pagination: Not implemented in the frontend; grid renders all filtered results.
flowchart TD
A["User Input"] --> B{"Search Term Empty?"}
B --> |Yes| C["Match All"]
B --> |No| D["Check Name/City/State Containment"]
C --> E["Match Standard"]
D --> E
E --> F{"Standard Selected?"}
F --> |No| G["Match All"]
F --> |Yes| H["Compare With Selected"]
G --> I["Match State"]
H --> I
I --> J{"State Selected?"}
J --> |No| K["Match All"]
J --> |Yes| L["Compare With Selected"]
K --> M["Match Group"]
L --> M
M --> N{"Group Selected?"}
N --> |No| O["Include Student"]
N --> |Yes| P["Check Standard In Group"]
P --> Q{"Included?"}
Q --> |Yes| O
Q --> |No| R["Exclude Student"]
Loading

Diagram sources

  • student-directory.tsx

Section sources

  • student-directory.tsx

Grade-Level Organization and Class Organization

  • Grade Groups: Pre-Primary, Primary, Middle, Secondary, Senior Secondary.
  • Class Organization: Students include standard and optional section; class-based queries supported by storage for student retrieval by class.
classDiagram
class Student {
+number id
+string name
+string? profileUrl
+string? avatar
+string city
+string state
+string standard
+string? section
}
class Storage {
+getUser(id) User
+getUsers(role) User[]
+getUsersByClass(className) User[]
}
Student <.. Storage : "queried by"
Loading

Diagram sources

  • student-directory.tsx
  • storage.ts

Section sources

  • student-directory.tsx
  • storage.ts

Contact Information Management

  • Display Fields: Name, city, state, standard/class, optional section, and profile URL.
  • Avatar Handling: Uses external avatar service or initials fallback computed from name.
  • Privacy Controls: Profile URL visibility depends on data availability; no explicit privacy toggles in the directory UI.
sequenceDiagram
participant UI as "Student Card"
participant Utils as "getInitials()"
UI->>Utils : Compute initials from name
Utils-->>UI : Initials string
UI->>UI : Render avatar or initials
Loading

Diagram sources

  • student-directory.tsx
  • utils.ts

Section sources

  • student-directory.tsx
  • utils.ts

Directory Navigation

  • Tabs: Switch between "All Students" and grade group tabs; each tab renders a filtered grid.
  • Reset Filters: Clear all selections with a single button.
  • Navigation Aids: Header and mobile navigation integrated into the page layout.

Section sources

  • student-directory.tsx
  • student-directory.tsx

Backend Routes and User Management

  • Authentication: Registration, login, logout endpoints with session management.
  • User Retrieval: Endpoint to fetch current user profile.
  • Workspace/Channel Messaging: Used for user relationships and communication; supports DMs and workspace channels.
sequenceDiagram
participant Client as "Client"
participant Auth as "Auth Routes"
participant Store as "Storage"
participant Mongo as "MongoDB"
Client->>Auth : POST /api/auth/register
Auth->>Store : CreateUser
Store->>Mongo : Insert user document
Mongo-->>Store : Inserted user
Store-->>Auth : User without password
Auth-->>Client : 201 Created
Loading

Diagram sources

  • routes.ts
  • storage.ts
  • db.ts

Section sources

  • routes.ts
  • routes.ts
  • routes.ts

Administrative User Management Features

  • Admin Dashboard UI: Provides tabs for User Management, Classes, Reports, and System Settings with placeholder actions.
  • Role-Specific Data: Configuration demonstrates role-based attributes (e.g., student classId, teacher subjects, principal institutionId).

Section sources

  • admin-dashboard.tsx
  • config.ts

Dependency Analysis

The system exhibits clear separation of concerns:

  • Client depends on shared schemas for type safety and on backend routes for data.
  • Server routes depend on storage for persistence and on shared schemas for validation.
  • Storage depends on MongoDB for data access.
graph LR
Client["Client (React)"] --> Routes["Server Routes"]
Routes --> Storage["Storage Layer"]
Storage --> MongoDB["MongoDB"]
Routes --> Schemas["Shared Schemas"]
Storage --> Schemas
Loading

Diagram sources

  • routes.ts
  • storage.ts
  • schema.ts
  • db.ts

Section sources

  • routes.ts
  • storage.ts
  • schema.ts
  • db.ts

Performance Considerations

  • Client-side Filtering: Current implementation filters in memory; for large datasets, consider server-side filtering and pagination.
  • Rendering: Grid rendering scales linearly with filtered results; virtualization could improve performance for large lists.
  • Database Queries: Use indexes on frequently queried fields (e.g., class, role) to optimize storage queries.
  • Caching: Implement caching for static grade groups and state lists to reduce recomputation.

Troubleshooting Guide

  • Authentication Issues: Verify session presence and role for protected routes.
  • User Not Found: Ensure user IDs exist in MongoDB and that the correct session is used.
  • Workspace/Channel Access: Confirm membership and proper workspace/channel ownership for DMs and pins.
  • Upload Failures: Validate multipart form data and file presence before processing.

Section sources

  • routes.ts
  • routes.ts
  • routes.ts

Conclusion

The User Directory System provides a robust foundation for browsing and searching students with grade-level grouping, filtering, and display. While the current frontend uses mocked data, the backend routes and storage layer support real user data retrieval and administrative features. Enhancements such as server-side filtering, pagination, and improved privacy controls would further strengthen the system for production use.

Clone this wiki locally