Back to Course Tutor

README

Course Tutor System

A comprehensive learning management system designed for students, self-learners, and study groups to structure their learning journeys with interactive note-taking capabilities.

✨ Latest Updates (v2.0.0)

New Features

  • Simplified Course Interface: Clean, distraction-free course page with drag-and-drop section reordering
  • Enhanced Note Management:
- Multiple markdown notes and canvas drawings per section - Auto-save with immediate backend persistence - Click-to-edit interface with markdown preview - New notes automatically open in edit mode
  • Improved PDF Export: Full support for notes and canvas images in PDF exports
  • Better Canvas Editor: Canvas drawings preserve state when switching between view/edit modes
  • Full CRUD API: Complete paragraph management with create, update, and delete endpoints

Fixed Issues

  • ✅ Notes now persist correctly after page refresh
  • ✅ Canvas images properly render in PDF exports (no more base64 strings)
  • ✅ CORS configuration fixed for frontend-backend communication
  • ✅ Canvas drawings no longer disappear when entering edit mode

Features

  • Course Management: Create and organize courses with hierarchical sections
  • Dual Note-Taking: Multiple markdown notes + canvas drawings per section
  • Simplified UI: Clean, focused interface with drag-and-drop section management
  • Real-time Saving: Automatic persistence of all changes
  • PDF Export: Export courses with all notes and drawings
  • Version History: Track all changes to notes with restore capabilities
  • Collaboration: Share courses via invite codes with role-based access

Tech Stack

  • Frontend: React + TypeScript + Vite + Tailwind CSS + shadcn/ui
  • Backend: Go + gqlgen (GraphQL)
  • Database: MySQL 8.0
  • DevOps: Docker + docker-compose
  • Testing: Vitest, Go testing, Cypress E2E

Prerequisites

  • Docker & Docker Compose
  • Node.js 20+ (for local development)
  • Go 1.21+ (for local development)
  • Make

Quick Start

Development Mode (Local)

bash
# Start full development environment with hot reload
./dev-all.sh

# Stop all services
./stop-all.sh

# Nuclear cleanup (if processes get stuck)
./kill-all.sh

# Fix Air root permission issues
./fix-air-root.sh

Development Mode (Docker) - Alternative

bash
# Start with Docker (avoids all permission issues)
./dev-docker.sh

# Stop Docker services
./stop-docker.sh

The development environment includes:

  • Backend with Air hot reload (local installation in backend/bin)
  • Frontend with Vite hot reload
  • MySQL database
  • Clean console output
  • No root permission issues
Access points:
  • Frontend: http://localhost:3001
  • Backend API: http://localhost:8082
  • GraphQL Playground: http://localhost:8082/graphql

Developer Docs (Docusaurus)

Preview the documentation site locally:

bash
./dev-all.sh                  # backend, frontend, and docs (http://localhost:3003)
DOCS=0 ./dev-all.sh           # skip docs site
DOCS_PORT=4000 ./dev-all.sh   # override docs port
# or run docs alone
./docs-site/dev-docs.sh

Manual Start

  • Clone the repository:

    • bash
    git clone https://github.com/yourusername/course-tutor.git
cd course-tutor

  • Create environment file:

    • bash
    cp .env.example .env
# Edit .env with your configuration

  • Start all services:

    • bash
    make up

  • Run database migrations:

    • bash
    make migrate

  • (Optional) Seed demo data:

    • bash
    make seed

    The application will be available at:

    • Frontend: http://localhost:3001
    • Backend API: http://localhost:8082
    • GraphQL Playground: http://localhost:8082/graphql
    Default demo credentials:
    • Email: demo@demo.com
    • Password: demo123

    Development Commands

    Service Management

    bash
    make up              # Start all services
make down            # Stop all services
make restart         # Restart all services
make logs            # View all logs
make backend-logs    # View backend logs only
make frontend-logs   # View frontend logs only

    Database

    bash
    make migrate         # Run migrations
make seed            # Seed demo data
make db-reset        # Reset database (drop and recreate)

    Testing

    bash
    make test            # Run all tests
make test-backend    # Run backend tests
make test-frontend   # Run frontend tests
make test-e2e        # Run Cypress E2E tests
make test-coverage   # Generate coverage reports

    Code Quality

    bash
    make lint            # Run linters
make format          # Format code
make check-schema    # Validate GraphQL schema

    GraphQL Development

    bash
    make gql-gen         # Generate GraphQL code for both backend and frontend

    Project Structure

    shell
    course-tutor/
├── backend/                 # Go backend service
│   ├── cmd/server/         # Main application entry
│   ├── graph/              # GraphQL schema & resolvers
│   ├── models/             # Domain models
│   ├── services/           # Business logic
│   ├── auth/               # Authentication & authorization
│   ├── database/           # Migrations & DB utilities
│   └── tests/              # Backend tests
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Route pages
│   │   ├── hooks/          # Custom React hooks
│   │   ├── graphql/        # Generated GraphQL types
│   │   └── lib/            # Utilities & configurations
│   ├── .storybook/         # Storybook configuration
│   └── cypress/            # E2E test specs
├── docs/                   # Documentation
├── docker-compose.yml      # Docker services configuration
└── Makefile               # Developer commands

    API Documentation

    GraphQL Schema

    The GraphQL schema is available at:

    • Development: http://localhost:8080/schema.graphql
    • GraphQL Playground: http://localhost:8080/graphql
    Key types:
    • User: System users with authentication
    • Course: Learning courses with ownership
    • Section: Hierarchical course content (max 4 levels)
    • Paragraph: Markdown notes with versioning
    • CanvasNote: Drawing/annotation space
    • ShareCode: Course invitation system

    Authentication

    The system uses httpOnly secure cookies for session management:

    • Register: mutation register(input: RegisterInput!)
    • Login: mutation login(input: LoginInput!)
    • Logout: mutation logout

    Core Features Implementation

    1. Section Hierarchy

    Sections support up to 4 levels of nesting:

    • Course → Module → Lesson → Sub-lesson
    • Automatic depth validation
    • Progress roll-up to parent sections

    2. Note Versioning

    All paragraph edits create immutable versions:

    • View version history
    • Compare changes (diff view)
    • Restore any previous version

    3. Canvas Notes

    Per-section drawing space supporting:

    • Shapes and freehand drawing
    • Text annotations
    • Image uploads with markup
    • Vector data stored as JSON

    4. Collaboration

    Share courses via invite codes:

    • Set role (Owner/Tutor/Contributor/Viewer)
    • Optional expiry date
    • Usage limits
    • Revocable codes

    5. AI Curriculum Import

    Import existing course outlines:

    • Paste or upload curriculum
    • AI service parses into section tree
    • Preview and edit before applying
    • Manual fallback if service unavailable

    Testing Strategy

    Unit Tests

    • Business logic validation
    • Service layer testing
    • GraphQL resolver testing

    Integration Tests

    • Full user workflows
    • Database operations
    • API endpoint testing

    E2E Tests (Cypress)

    • User registration & login
    • Course creation & management
    • Note-taking workflows
    • Collaboration features

    Component Tests (Storybook)

    • Visual regression testing
    • Accessibility compliance
    • Component interaction testing

    Deployment

    Production Build

    bash
    # Build production images
make build

# Run with production config
docker-compose -f docker-compose.prod.yml up

    Environment Variables

    Required for production:

    • JWT_SECRET: Strong secret for JWT signing
    • DB_HOST, DB_USER, DB_PASSWORD: Database credentials
    • CORS_ORIGINS: Allowed frontend origins
    • ENVIRONMENT: Set to "production"

    Contributing

  • Fork the repository
  • Create a feature branch
  • Make your changes
  • Add tests for new functionality
  • Ensure all tests pass: make test
  • Submit a pull request

    • Security Considerations

    • All inputs are validated and sanitized
    • SQL injection prevention via parameterized queries
    • XSS protection through content sanitization
    • CSRF protection on state-changing operations
    • Rate limiting on authentication endpoints
    • Secure session management with httpOnly cookies

    Performance Optimizations

    • GraphQL query batching with DataLoader
    • Database query optimization with indexes
    • Frontend caching with Apollo Client
    • Pagination for large datasets
    • Lazy loading for nested sections

    Troubleshooting

    Common Issues

  • Port conflicts: Ensure ports 3000, 6006, 8080, 3306 are available
  • Database connection: Wait for MySQL to be fully ready (health check)
  • GraphQL codegen: Backend must be running for schema fetch

    • Debug Commands

    bash
    # Check service status
docker-compose ps

# View specific logs
docker-compose logs -f [service-name]

# Access MySQL shell
docker-compose exec mysql mysql -u root -p

# Rebuild specific service
docker-compose build --no-cache [service-name]

    License

    MIT License - See LICENSE file for details

    Support

    For issues and questions:

    • GitHub Issues: Report bugs
    • Documentation: See /docs folder
    • API Schema: http://localhost:8080/graphql

    Roadmap

    • [x] Export to PDF with full note and canvas support
    • [x] Simplified course interface with drag-and-drop
    • [x] Multiple notes per section support
    • [ ] Real-time collaborative editing
    • [ ] Mobile application
    • [ ] Advanced analytics dashboard
    • [ ] Spaced repetition integration
    • [ ] Plugin system for extensions
    • [ ] AI-powered note suggestions
    • [ ] Video lecture integration

    © 2026 Jonathan Leahy · v0.9.3