📚 Digital-Logbook

A Modern Mentorship & Learning Management Platform

Features • Tech Stack • Quick Start • Documentation • Contributing

📖 Table of Contents

Overview
Features
Tech Stack
Prerequisites
Quick Start
Installation
Environment Variables
Database Setup
Project Structure
Available Scripts
API Documentation
Testing
Deployment
Troubleshooting
Documentation
Contributing
License

🌟 Overview

Digital-Logbook is a comprehensive full-stack web application designed to facilitate structured learning relationships between mentees and mentors. It provides a robust platform for tracking learning activities, managing projects, delivering feedback, and generating performance reports.

What Problem Does It Solve?

Activity Tracking: Students log daily learning activities with time spent and technologies used
Mentor Oversight: Mentors review student progress and provide timely, structured feedback
Project Management: Organize learning across multiple domains (software, film, training, research)
Performance Analytics: Generate detailed reports on mentor activities and student progress
User Administration: Streamlined user management, invitations, and role-based access control
Gamification: Award badges to recognize and motivate student achievements

Who Is It For?

Students/Mentees: Track learning progress, receive feedback, and earn recognition
Mentors: Monitor mentees, provide feedback, and log mentoring activities
Super Admins: Manage users, projects, invitations, and platform analytics

✨ Features

For Students

📝 Activity Logging - Log daily activities with time tracking and technology tags
📊 Progress Dashboard - Visualize learning progress and performance metrics
🏆 Gamification - Earn badges for achievements and milestones
👤 Profile Management - Manage personal information and learning preferences
📅 Task Calendar - Calendar view of activities and deadlines

For Mentors

👥 Mentee Management - View and manage assigned students
✅ Feedback System - Approve, reject, or provide feedback on student activities
📈 Bulk Reporting - Generate comprehensive reports (PDF/Excel export)
📅 Activity Calendar - Calendar view of all mentee activities
⏱️ Time Tracking - Log mentoring hours and activities

For Super Admins

🎯 Project Management - Create and manage projects across multiple domains
👤 User Management - Create, deactivate, and manage user roles
📧 Bulk Invitations - Send and track email invitations with unique tokens
📊 Analytics Dashboard - Platform-wide analytics and insights
🏆 Badge Management - Create and award achievement badges
⚠️ Warning System - Flag and monitor concerning activity patterns
📄 Report Management - View and manage generated reports

Cross-Platform Features

🔐 JWT Authentication - Secure token-based authentication
🎨 Modern UI - Beautiful, responsive interface with TailwindCSS
🚀 Type-Safe APIs - End-to-end type safety with oRPC
📱 Responsive Design - Mobile-friendly interface
🌙 Dark Mode Support - Theme switching capability
📧 Email Notifications - Automated email notifications via Nodemailer
🔄 Background Jobs - Async task processing with BullMQ

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
Next.js	14.2.5	React framework with SSR/SSG
React	18.x	UI library
TypeScript	5.x	Type-safe JavaScript
TailwindCSS	Latest	Utility-first CSS framework
Radix UI	Latest	Accessible component primitives
shadcn/ui	Latest	Re-usable component library
React Hook Form	7.x	Form validation
Zod	3.x	Schema validation
TanStack Query	v5	Data fetching & caching

Backend

Technology	Version	Purpose
Next.js API Routes	14.2.5	API endpoints
oRPC	1.13.14	Type-safe RPC framework
Prisma	5.19.1	ORM for database access
PostgreSQL	16.3	Relational database
Redis	Latest	Caching & job queue
BullMQ	5.x	Background job processing
Jose	5.x	JWT token handling
bcrypt	5.x	Password hashing
Nodemailer	6.x	Email sending

DevOps & Tools

Technology	Version	Purpose
Docker	27.1.2+	Containerization
Docker Compose	Latest	Multi-container orchestration
Jest	Latest	Testing framework
ESLint	Latest	Code linting
Prettier	Latest	Code formatting

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js: v22.7.0 (use nvm for version management)
npm: 10.8.2
Docker: 27.1.2+ (Install Docker)
Docker Compose: Latest version
Git: Latest version

Note: Using the exact Node.js and npm versions is crucial for compatibility.

🚀 Quick Start

Get up and running in 5 minutes:

# 1. Clone the repository
git clone https://github.com/tracet2t/Digital-Logbook.git
cd Digital-Logbook

# 2. Navigate to server directory
cd server

# 3. Use the correct Node.js version
nvm use
# If not installed, run: nvm install

# 4. Install npm version
npm install npm@10.8.2

# 5. Install dependencies
npm install

# 6. Start Docker containers (from root directory)
cd ..
docker compose up --build

# 7. Return to server directory
cd server

# 8. Run database migrations
npm run migrate:maindb

# 9. Seed the database (optional)
npm run seed

# 10. Start the development server
npm run dev

# 11. Open your browser
# Application: http://localhost:3000
# PgAdmin: http://localhost:8080

💻 Installation

Step 1: Clone the Repository

git clone https://github.com/tracet2t/Digital-Logbook.git
cd Digital-Logbook

Step 2: Set Up Node.js Environment

cd server

# Install Node Version Manager (if not already installed)
# https://github.com/nvm-sh/nvm#installing-and-updating

# Use the required Node.js version
nvm use

# If the version is not installed
nvm install

# Install the correct npm version
npm install npm@10.8.2

Step 3: Install Dependencies

npm install

Step 4: Configure Environment Variables

Create a .env file in the server/ directory:

cp dotenv .env

Edit .env with your configuration (see Environment Variables section).

🔐 Environment Variables

Create a .env file in the server/ directory with the following variables:

# Database Configuration
DATABASE_URL="postgresql://postgres:your-db-password@pgdb:5432/postgres?schema=public"
NEXT_PUBLIC_POSTGRES_HOST=pgdb
NEXT_PUBLIC_POSTGRES_USER=postgres
NEXT_PUBLIC_POSTGRES_PASSWORD=your-db-password

# Redis Configuration (for job queue)
NEXT_PUBLIC_REDIS_HOST=redis
NEXT_PUBLIC_REDIS_PORT=6379

# Authentication
JWT_SECRET=your-super-secret-jwt-key-min-32-characters
BASE_URL=http://localhost:3000

# Email Configuration (SMTP)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASSWORD=your-email-password
SMTP_FROM=noreply@example.com

# Application Configuration
NODE_ENV=development

⚠️ Security Warning: Never commit your .env file to version control. The .env file is already in .gitignore.

Environment Variable Descriptions

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`JWT_SECRET`	Secret key for JWT token signing (min 32 chars)	`your-super-secret-key`
`BASE_URL`	Application base URL	`http://localhost:3000`
`SMTP_HOST`	SMTP server hostname	`smtp.gmail.com`
`SMTP_PORT`	SMTP server port	`587` or `465`
`SMTP_USER`	SMTP username/email	`your-email@example.com`
`SMTP_PASSWORD`	SMTP password	`your-app-password`

🗄️ Database Setup

Using Docker (Recommended)

The project uses Docker Compose to manage PostgreSQL, Redis, and pgAdmin:

# From project root directory
# First time setup
docker compose up --build

# Subsequent runs
docker compose up

This will start:

PostgreSQL on localhost:5432
Redis on localhost:6379
pgAdmin on localhost:8080 (admin@example.com / admin)

Run Migrations

cd server
npm run migrate:maindb

Seed Database (Optional)

npm run seed

Database Tools

# Open Prisma Studio (visual database editor)
npm run db:studio

# Reset database (⚠️ deletes all data)
npm run db:delete

📁 Project Structure

Digital-Logbook/
├── server/                          # Main application directory
│   ├── src/
│   │   ├── app/                     # Next.js pages & layouts
│   │   │   ├── admin/              # Super admin pages
│   │   │   ├── mentor/             # Mentor pages
│   │   │   ├── student/            # Student pages
│   │   │   └── login/              # Authentication pages
│   │   ├── components/             # React components
│   │   │   ├── admin/              # Admin-specific components
│   │   │   ├── mentor/             # Mentor-specific components
│   │   │   └── ui/                 # Shared UI components (shadcn/ui)
│   │   ├── routers/                # oRPC API routers
│   │   ├── repositories/           # Data access layer (Prisma)
│   │   ├── services/               # Business logic
│   │   ├── server_actions/         # Next.js Server Actions
│   │   ├── middlewares/            # Authentication & routing middleware
│   │   ├── schemas/                # Zod validation schemas
│   │   ├── types/                  # TypeScript type definitions
│   │   ├── utils/                  # Utility functions
│   │   ├── lib/                    # Library configurations
│   │   └── worker/                 # Background job workers (BullMQ)
│   ├── prisma/
│   │   ├── schema.prisma           # Database schema
│   │   ├── seed.mjs                # Database seeding script
│   │   └── migrations/             # Database migrations
│   ├── public/                     # Static assets
│   ├── test/                       # Test files
│   └── package.json                # Dependencies & scripts
├── docs/                           # Documentation
│   ├── api/                        # API documentation
│   ├── QA-Testcases/               # Test cases
│   └── schema/                     # Database schema docs
├── init/                           # Database initialization scripts
├── docker-compose.yml              # Docker services configuration
└── README.md                       # This file

📜 Available Scripts

Navigate to the server/ directory and run:

Script	Command	Description
Development	`npm run dev`	Start development server on port 3000
Build	`npm run build`	Build production bundle
Start	`npm start`	Start production server
Lint	`npm run lint`	Run ESLint
Test	`npm test`	Run Jest tests
Prisma Generate	`npm run generate`	Generate Prisma Client
Migrate DB	`npm run migrate:maindb`	Run database migrations
Migrate Test DB	`npm run migrate:testdb`	Run test database migrations
Seed DB	`npm run seed`	Seed database with initial data
Prisma Studio	`npm run db:studio`	Open Prisma Studio (DB GUI)
Reset DB	`npm run db:delete`	Reset database (⚠️ deletes all data)

📚 API Documentation

oRPC Framework

This project uses oRPC for type-safe API development. oRPC provides:

End-to-end type safety
Automatic OpenAPI schema generation
Runtime validation with Zod
React Query integration

API Routes

API routers are located in server/src/routers/:

Authentication: User login, registration, password reset
Projects: CRUD operations for projects
Invitations: Bulk invitations and invitation management
Activities: Student activity logging and retrieval
Feedback: Mentor feedback on student activities
Reports: Report generation and management
Users: User management (admin)
Badges: Badge creation and awarding

Documentation Links

🧪 Testing

The project uses Jest for unit and integration testing.

Run Tests

cd server

# Run all tests
npm test

# Run tests for specific file
npm test -- invitationRepository.test.ts

# Run tests in watch mode
npm test -- --watch

Test Coverage

Test files are located in server/test/:

invitationRepository.test.ts - Invitation repository tests
menteeTechnologyRepository.test.ts - Technology repository tests
preliminaries.test.ts - Preliminary setup tests
studentTaskTechnologiesRoute.test.ts - Route tests

Test Documentation

Comprehensive test cases are documented in docs/QA-Testcases/:

🚢 Deployment

Docker Deployment

The application is containerized and can be deployed using Docker:

# Build and start all services
docker compose up --build -d

# View logs
docker compose logs -f nextjs-app

# Stop services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

Production Considerations

Environment Variables: Use production values for all sensitive variables
Database: Use managed PostgreSQL service (e.g., AWS RDS, Supabase)
Redis: Use managed Redis service (e.g., Redis Cloud, AWS ElastiCache)
Secrets Management: Use environment variable managers (e.g., AWS Secrets Manager)
SSL/TLS: Enable HTTPS with valid SSL certificates
Monitoring: Set up logging and monitoring (e.g., Sentry, DataDog)
Backups: Configure automated database backups

Recommended Platforms

Vercel - Next.js optimized deployment
Railway - Full-stack deployment
AWS - EC2, ECS, or App Runner
DigitalOcean - App Platform or Droplets

🔧 Troubleshooting

Common Issues

Port Already in Use

# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Or change port in package.json dev script
"dev": "next dev -p 3001"

Docker Issues

# Restart Docker services
docker compose down
docker compose up --build

# Clean Docker cache
docker system prune -a

Database Connection Issues

Ensure Docker containers are running: docker compose ps
Check DATABASE_URL in .env file
Verify PostgreSQL container health: docker logs pgdb

Prisma Client Issues

# Regenerate Prisma Client
npm run generate

# Reset and regenerate
npm run db:delete
npm run migrate:maindb
npm run generate

Node Version Mismatch

# Ensure correct Node.js version
nvm use

# If not installed
nvm install 22.7.0
nvm use 22.7.0

Module Not Found Errors

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

📖 Documentation

Comprehensive documentation is available in the docs/ directory:

Setup & Installation

Environment Setup Guide

Feature Guides

API Documentation

Developer Guides

Database

Database Schema Documentation

Testing

QA Test Cases

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Workflow

Fork the repository

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Follow existing code style
- Add tests for new features
- Update documentation as needed
Run tests
```
npm test
npm run lint
```

Commit your changes

git commit -m "feat: add amazing feature"

Push to your fork

git push origin feature/your-feature-name

Create a Pull Request

Code Style Guidelines

TypeScript: Use strict type checking
Components: Follow React best practices
Naming: Use descriptive variable and function names
Comments: Add JSDoc comments for complex functions
Formatting: Run Prettier before committing
Testing: Write tests for new features

Commit Message Convention

Follow Conventional Commits:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

Project Structure Conventions

Components: Place in appropriate domain folder (admin/, mentor/, student/)
Routers: Use oRPC router pattern
Repositories: Follow repository pattern for data access
Schemas: Define Zod schemas for validation
Types: Add TypeScript interfaces in types/ directory

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 tracet2t

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🙏 Acknowledgments

Next.js - The React Framework
Prisma - Next-generation ORM
oRPC - Type-safe RPC framework
shadcn/ui - Beautiful UI components
Radix UI - Accessible component primitives
TailwindCSS - Utility-first CSS framework

📞 Support

For questions, issues, or feature requests:

Issues: GitHub Issues
Discussions: GitHub Discussions

This project and all associated intellectual property, including but not limited to source code, documentation, design, and trademarks, are the exclusive property of Tracet2t.

While this software is licensed under the MIT License (see LICENSE file), all rights not expressly granted by the license are reserved by Tracet2t.

Made with ❤️ by Tracet2t

⭐ Star this repository if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 679 Commits
.github		.github
.vscode		.vscode
docs		docs
init		init
mk_docs		mk_docs
server		server
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation