Skip to content

Contributing Guidelines

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

Contributing Guidelines

**Referenced Files in This Document** - [CONTRIBUTING.md](file://CONTRIBUTING.md) - [CLA.md](file://CLA.md) - [.github/workflows/cla.yml](file://.github/workflows/cla.yml) - [CODE_OF_CONDUCT.md](file://CODE_OF_CONDUCT.md) - [README.md](file://README.md) - [LOCAL_SETUP.md](file://LOCAL_SETUP.md) - [CHANGELOG.md](file://CHANGELOG.md) - [.github/pull_request_template.md](file://.github/pull_request_template.md) - [package.json](file://package.json) - [server/index.ts](file://server/index.ts) - [server/routes.ts](file://server/routes.ts) - [client/src/App.tsx](file://client/src/App.tsx) - [client/src/main.tsx](file://client/src/main.tsx) - [client/src/tests/LoginPage.test.tsx](file://client/src/tests/LoginPage.test.tsx) - [client/src/hooks/use-chat-ws.ts](file://client/src/hooks/use-chat-ws.ts) - [client/src/lib/chat-api.ts](file://client/src/lib/chat-api.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
  10. Appendices

Introduction

This document provides comprehensive contributing guidelines for PersonalLearningPro. It covers the development workflow (fork and clone, branching, commits), code review and pull request process, testing expectations, project structure, coding standards, architectural principles, CLA requirements, contributor onboarding, community guidelines, issue and feature request processes, documentation contributions, and release/versioning/maintenance responsibilities.

Project Structure

PersonalLearningPro is a full-stack monorepo-like application with a single Express server serving both the API and a Vite-built React frontend on port 5001. The repository is organized into client, server, shared, and supporting configuration files.

graph TB
subgraph "Client (React + Vite)"
C_App["client/src/App.tsx"]
C_Main["client/src/main.tsx"]
C_Components["client/src/components/*"]
C_Pages["client/src/pages/*"]
C_Lib["client/src/lib/*"]
C_Hooks["client/src/hooks/*"]
end
subgraph "Server (Express)"
S_Index["server/index.ts"]
S_Routes["server/routes.ts"]
S_Lib["server/lib/*"]
S_MessagePal["server/messagepal/*"]
end
subgraph "Shared"
SH_Schema["shared/schema.ts"]
end
C_App --> C_Main
C_App --> C_Pages
C_App --> C_Components
C_App --> C_Lib
C_App --> C_Hooks
C_Lib --> S_Routes
C_Hooks --> S_Index
S_Index --> S_Routes
S_Routes --> SH_Schema
Loading

Diagram sources

  • client/src/App.tsx
  • client/src/main.tsx
  • server/index.ts
  • server/routes.ts
  • shared/schema.ts

Section sources

  • README.md
  • client/src/App.tsx
  • client/src/main.tsx
  • server/index.ts
  • server/routes.ts

Core Components

  • Frontend entry and routing: The React application initializes in main.tsx and renders App.tsx, which defines role-aware routing and layout wrappers.
  • Backend entry and middleware: The Express server initializes sessions, logging, static serving, and routes, and serves both API and client on port 5001.
  • API surface: Routes.ts defines authentication, user, test, question, attempt, answer, OCR, AI evaluation, and chat/workspace/message endpoints.
  • Shared schema: shared/schema.ts defines Zod-based validation schemas used across client and server.

Key implementation references:

  • Frontend entry and routing: client/src/main.tsx, client/src/App.tsx
  • Server initialization and port: server/index.ts
  • API routes registration: server/routes.ts
  • Shared schema: shared/schema.ts

Section sources

  • client/src/main.tsx
  • client/src/App.tsx
  • server/index.ts
  • server/routes.ts
  • shared/schema.ts

Architecture Overview

The system follows a monolithic Express server architecture that:

  • Serves the React SPA built by Vite.
  • Provides REST APIs for all features (authentication, tests, OCR, AI, chat).
  • Integrates optional third-party services (Firebase, OpenAI) and hybrid storage (PostgreSQL and MongoDB).
  • Supports real-time features via WebSockets for chat and MessagePal.
graph TB
Browser["Browser"]
FE["React SPA<br/>client/src/*"]
BE["Express Server<br/>server/index.ts"]
Routes["Routes<br/>server/routes.ts"]
Storage["Storage Layer<br/>server/storage.ts"]
DB_PG["PostgreSQL"]
DB_Mongo["MongoDB"]
DB_Cass["Cassandra (MessagePal)"]
Firebase["Firebase (optional)"]
OpenAI["OpenAI (optional)"]
Browser --> FE
FE --> BE
BE --> Routes
Routes --> Storage
Storage --> DB_PG
Storage --> DB_Mongo
Storage --> DB_Cass
BE --> Firebase
BE --> OpenAI
Loading

Diagram sources

  • server/index.ts
  • server/routes.ts
  • README.md

Section sources

  • server/index.ts
  • README.md

Detailed Component Analysis

Development Workflow

  • Fork and clone the repository.
  • Choose setup option:
    • Docker (recommended): Build and run with docker compose; hot reload is supported.
    • Manual setup: Install dependencies, configure environment variables, run dev server.
  • Create feature branches using the convention: feature/your-feature-name.
  • Run TypeScript checks before committing.
  • Push and open a pull request targeting the main branch.

References:

  • Fork/clone and setup: CONTRIBUTING.md
  • Branch naming and workflow: CONTRIBUTING.md
  • TypeScript checks: CONTRIBUTING.md, package.json

Section sources

  • CONTRIBUTING.md
  • package.json

Code Review and Pull Request Process

  • Use the provided pull request template checklist to ensure completeness.
  • Ensure no duplicate PRs, self-review, documentation updates, absence of new warnings, tests included, local passing, and dependent changes merged.
  • CLA signing is required before merging; the CLA Assistant bot will guide contributors.

References:

  • PR template checklist: .github/pull_request_template.md
  • CLA workflow: .github/workflows/cla.yml
  • CLA instructions: CLA.md

Section sources

  • .github/pull_request_template.md
  • .github/workflows/cla.yml
  • CLA.md

Testing Requirements

  • Unit tests are written with Vitest and Testing Library for React.
  • Example test coverage includes form input updates, validation errors, and submission behavior.
  • Run tests locally using the project’s test script.

References:

  • Test example: client/src/tests/LoginPage.test.tsx
  • Test script: package.json

Section sources

  • client/src/tests/LoginPage.test.tsx
  • package.json

Coding Standards

  • The project does not enforce a code formatter or linter; follow the existing code style in the files being edited.
  • Maintain consistency with surrounding code and adhere to TypeScript strictness enforced by the project’s type-checking script.

References:

  • Coding style note: CONTRIBUTING.md
  • Type-check script: package.json

Section sources

  • CONTRIBUTING.md
  • package.json

Issue Reporting and Feature Requests

  • Report bugs with a clear title, reproduction steps, and relevant error messages or screenshots.
  • Suggest enhancements with a clear title and description of the problem solved by the enhancement.

References:

  • Bug report guidance: CONTRIBUTING.md
  • Enhancement suggestion guidance: CONTRIBUTING.md

Section sources

  • CONTRIBUTING.md

Documentation Contributions

  • Contribute improvements to existing documentation files (CONTRIBUTING.md, README.md, LOCAL_SETUP.md, etc.) following the same workflow and PR process.

References:

  • Contribution workflow: CONTRIBUTING.md

Section sources

  • CONTRIBUTING.md

Release Process, Versioning, and Maintenance

  • Versioning follows semantic versioning as indicated by the changelog.
  • Releases are tracked in the changelog with “Added,” “Changed,” and “Fixed” categories.
  • Maintenance responsibilities include keeping dependencies updated and ensuring backward compatibility where applicable.

References:

  • Changelog and semantic versioning: CHANGELOG.md

Section sources

  • CHANGELOG.md

Contributor Onboarding and Community Guidelines

  • Join the community Discord for discussions and support.
  • Follow the Code of Conduct in all interactions.
  • Top contributor recognition and rewards are available for sustained high-quality contributions.

References:

  • Community and reward info: CONTRIBUTING.md
  • Code of Conduct: CODE_OF_CONDUCT.md

Section sources

  • CONTRIBUTING.md
  • CODE_OF_CONDUCT.md

API Workflow Example: Chat WebSocket Integration

This sequence illustrates how the frontend establishes a WebSocket connection, joins a channel, and receives events.

sequenceDiagram
participant FE as "Frontend (use-chat-ws.ts)"
participant WS as "WebSocket Server (/ws/chat)"
participant API as "HTTP API (chat-api.ts)"
FE->>WS : "Connect ws/wss : //host/ws/chat"
WS-->>FE : "Connected"
FE->>WS : "join_channel {channelId}"
WS-->>FE : "joined_channel {channelId}"
API->>WS : "Send message via HTTP (optional)"
WS-->>FE : "new_message"
FE->>WS : "typing"
WS-->>FE : "user_typing"
FE->>WS : "mark_read {messageId}"
WS-->>FE : "message_read"
WS-->>FE : "user_presence"
Loading

Diagram sources

  • client/src/hooks/use-chat-ws.ts
  • client/src/lib/chat-api.ts

Section sources

  • client/src/hooks/use-chat-ws.ts
  • client/src/lib/chat-api.ts

Frontend Routing and Layout

The frontend uses a central App.tsx with role-aware routing and a layout wrapper that controls margins and full-width rendering for specific pages.

flowchart TD
Start(["App.tsx"]) --> LoadAuth["Load auth context"]
LoadAuth --> IsLoading{"Auth loading?"}
IsLoading --> |Yes| ShowLoader["Show loading spinner"]
IsLoading --> |No| HasUser{"Has authenticated user?"}
HasUser --> |No| ShowAuthDialog["Show auth dialog"]
HasUser --> |Yes| GetRole["Get user role"]
GetRole --> RouteMap{"Route lookup"}
RouteMap --> Dashboard["Role-specific dashboard"]
RouteMap --> Features["Feature routes (create-test, ocr-scan, analytics, ai-tutor, student-directory)"]
RouteMap --> Messages["Messages and MessagePal"]
RouteMap --> NotFound["404 fallback"]
Dashboard --> Layout["Apply AppLayout wrapper"]
Features --> Layout
Messages --> Layout
Layout --> Render["Render with Sidebar and main content"]
Loading

Diagram sources

  • client/src/App.tsx

Section sources

  • client/src/App.tsx

Dependency Analysis

The project uses a mix of client-side and server-side dependencies, including UI components, state management, HTTP clients, and optional integrations.

graph LR
Pkg["package.json"]
Pkg --> FE_Deps["Frontend deps (React, Radix UI, shadcn/ui)"]
Pkg --> BE_Deps["Backend deps (Express, ws, multer, mongoose, cassandra-driver)"]
Pkg --> Tools["Dev tools (Vite, Vitest, TypeScript, esbuild)"]
Pkg --> Opt["Optional (Firebase, OpenAI, bufferutil)"]
Loading

Diagram sources

  • package.json

Section sources

  • package.json

Performance Considerations

  • Hot reload is supported via bind-mounted source directories in Docker; avoid unnecessary rebuilds by editing files directly.
  • Keep API responses concise; the server logs API calls with response bodies for debugging.
  • Prefer paginated queries for chat/message history to reduce payload sizes.

References:

  • Hot reload note: README.md
  • Logging middleware: server/index.ts

Section sources

  • README.md
  • server/index.ts

Troubleshooting Guide

Common setup and runtime issues:

  • Port conflicts: Change the port in the server entry if 5001 is in use.
  • Firebase authentication: Ensure Google authentication is enabled and all VITEFIREBASE* variables are set.
  • Environment variables: Confirm .env is at the project root and restart the dev server after changes.
  • npm install failures: Perform a clean install by removing node_modules and package-lock.json.
  • Database connectivity: Verify PostgreSQL and MongoDB are running and connection strings are correct.

References:

  • Port and troubleshooting notes: LOCAL_SETUP.md

Section sources

  • LOCAL_SETUP.md

Conclusion

By following these guidelines—using the recommended development workflow, adhering to the code style, fulfilling testing and PR requirements, and complying with the CLA and Code of Conduct—you contribute effectively to PersonalLearningPro. Engage with the community, keep documentation and tests up to date, and help maintain a high-quality, accessible platform.

Appendices

Appendix A: Quick Setup References

  • Docker setup: README.md
  • Manual setup: LOCAL_SETUP.md

Section sources

  • README.md
  • LOCAL_SETUP.md

Clone this wiki locally