The Homeschool Guide

A teacher's assistant app for homeschooling that reduces mental load and turns chaos into calm.

"Don't Panic" - If it's not easier than Excel, it has failed.

Features

Core Functionality

Activity Logging - Timer-based tracking with one-tap subject selection
Progress Dashboard - Visual charts showing time distribution across subjects
Lesson Planning - Weekly calendar view with drag-and-drop scheduling
AI Insights - Weekly Claude-powered analysis with suggestions and highlights
Offline-First - Works without internet, syncs when connected

Cross-Device Experience

Feature	Mobile (iPhone)	Desktop
Bottom Navigation	✅	Hidden
Quick Action Sheet	✅ Swipe-up	Hidden
Keyboard Shortcuts	Hidden	✅ Full support
Multi-column Layout	Single column	✅ 2-3 columns
Hover Tooltips	Hidden	✅ On hover
PWA Install Prompt	✅	Native browser

Architecture

flowchart TB
    subgraph Client [Client - PWA]
        UI[React UI]
        IDB[(IndexedDB)]
        SW[Service Worker]
    end
    
    subgraph Server [Server - Docker]
        API[Express API]
        DB[(PostgreSQL)]
        N8N[n8n Workflows]
    end
    
    subgraph External [External Services]
        CLAUDE[Claude AI API]
        SMTP[Email SMTP]
    end
    
    UI --> IDB
    UI --> SW
    SW --> API
    IDB -.->|Sync| API
    API --> DB
    N8N --> API
    N8N --> CLAUDE
    N8N --> SMTP

Data Flow (Offline-First)

User action → Writes to IndexedDB immediately
Sync engine → Detects network status
On reconnect → Pushes pending changes to API
Conflicts → Resolved with server-wins strategy
UI updates → Reactive via useLiveQuery hooks

Quick Start

Prerequisites

Node.js 20+ (check .nvmrc)
pnpm 9+ (npm install -g pnpm)
Docker Desktop
Git

Installation

# Clone the repository
git clone https://github.com/ChristopherWampler/Homeschool_App.git
cd Homeschool_App

# Install dependencies
pnpm install

# Copy environment files
cp docker/.env.example docker/.env
cp apps/web/.env.example apps/web/.env.local
cp apps/api/.env.example apps/api/.env.local

# Generate Prisma client
pnpm --filter database db:generate

# Start development servers
pnpm dev

Access Points

Service	URL	Description
Frontend	http://localhost:3000	React PWA
API	http://localhost:3001	Express server
PostgreSQL	localhost:5433	Database
n8n	http://localhost:5678	Automation

Development

Common Commands

# Start all development servers
pnpm dev

# Run specific app
pnpm --filter web dev
pnpm --filter api dev

# Build all packages
pnpm build

# Type checking
pnpm type-check

# Linting
pnpm lint

# Format code
pnpm format

Database Commands

pnpm --filter database db:generate    # Generate Prisma client
pnpm --filter database db:migrate     # Run migrations
pnpm --filter database db:seed        # Seed test data
pnpm --filter database db:studio      # Open Prisma Studio
pnpm --filter database db:reset       # Reset database

Docker Commands

pnpm run docker:up     # Start all services
pnpm run docker:down   # Stop all services
docker-compose -f docker/docker-compose.yml logs -f  # View logs

Project Structure

Homeschooling_App/
├── apps/
│   ├── web/                    # React PWA frontend
│   │   ├── src/
│   │   │   ├── components/     # Shared UI components
│   │   │   ├── features/       # Feature modules
│   │   │   │   ├── activities/ # Activity logging
│   │   │   │   ├── planning/   # Lesson planning
│   │   │   │   ├── progress/   # Dashboard & charts
│   │   │   │   └── insights/   # AI insights
│   │   │   ├── hooks/          # Custom React hooks
│   │   │   ├── pages/          # Route pages
│   │   │   ├── services/       # API & offline services
│   │   │   └── stores/         # Zustand stores
│   │   └── e2e/                # Playwright E2E tests
│   └── api/                    # Express backend
│       └── src/
│           ├── controllers/    # Request handlers
│           ├── routes/         # API routes
│           └── services/       # Business logic
├── packages/
│   ├── database/               # Prisma schema & client
│   ├── shared-types/           # TypeScript types
│   ├── utils/                  # Shared utilities
│   ├── typescript-config/      # Shared TS configs
│   └── eslint-config/          # Shared ESLint configs
├── docker/                     # Docker Compose configs
│   └── n8n/workflows/          # n8n workflow exports
├── docs/                       # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT.md
│   ├── DEVELOPMENT.md
│   └── TESTING.md
└── scripts/                    # Utility scripts

Technology Stack

Frontend

Technology	Version	Purpose
React	18.3	UI framework
TypeScript	5.7	Type safety
Vite	6.0	Build tool
React Router DOM	7.12	Routing
React Hook Form	7.71	Form handling
Zod	3.24	Validation
Recharts	3.6	Charts
Zustand	5.0	State management
Tailwind CSS	3.4	Styling
Dexie.js	4.2	IndexedDB
vite-plugin-pwa	1.2	PWA & Service Worker

Backend

Technology	Version	Purpose
Node.js	20+	Runtime
Express	4.21	Web framework
Prisma	6.19	ORM
PostgreSQL	16	Database

DevOps

Technology	Purpose
PNPM	Package manager
Turborepo	Build orchestration
Docker	Containerization
GitHub Actions	CI/CD
n8n	Workflow automation

Testing

Test Commands

# Run all tests
pnpm test

# Unit tests with coverage
pnpm --filter web test:coverage
pnpm --filter api test

# E2E tests
pnpm --filter web test:e2e

# E2E with UI
pnpm --filter web test:e2e:ui

Coverage Targets

Package	Target
@homeschool/utils	90%
@homeschool/api	80%
@homeschool/web	70%

Deployment

Target Environment

Host: Neptune HX99G home server (Windows)
Runtime: Docker containers
Ports: 3000 (web), 3001 (API), 5433 (PostgreSQL), 5678 (n8n)

Production Build

# Build all packages
pnpm build

# Start with Docker
docker-compose -f docker/docker-compose.yml up -d

See docs/DEPLOYMENT.md for detailed instructions.

Roadmap

Phase	Status	Description
1	✅ Complete	Foundation & Test Infrastructure
2	✅ Complete	Offline-First Architecture
3	✅ Complete	Daily Activity Logging
4	✅ Complete	Progress Tracking & Visualization
5	✅ Complete	Planning & Scheduling
6	✅ Complete	n8n Automation (AI Insights)
7	✅ Complete	Error Handling & Resilience
8	✅ Complete	Cross-Device Optimization
9	🔄 Next	Excel Data Migration

Keyboard Shortcuts

Global (Desktop Only)

Shortcut	Action
`?`	Show keyboard shortcuts help
`G`	Go to Activity Log
`D`	Go to Dashboard
`P`	Go to Planning
`I`	Go to Insights
`Escape`	Close modals/dialogs

Activity Log Page

Shortcut	Action
`N`	New manual entry
`S`	Stop timer
`1-6`	Quick start subject

Dashboard Page

Shortcut	Action
`R`	Refresh data
`T`	View Today
`W`	View This Week
`M`	View This Month

Planning Page

Shortcut	Action
`N`	New lesson
`W`	Weekly view
`D`	Daily view

Troubleshooting

Common Issues

Database Connection Failed

# Ensure PostgreSQL is running
docker-compose -f docker/docker-compose.yml up -d postgres

# Check connection
pnpm --filter database db:studio

Service Worker Not Updating

Open DevTools → Application → Service Workers
Check "Update on reload"
Clear cache and hard reload

Offline Sync Issues

Check network status in app (sync indicator)
Open DevTools → Application → IndexedDB
View homeschool-db for pending changes

PWA Not Installing

Ensure HTTPS (or localhost)
Check manifest at /manifest.webmanifest
Verify service worker is registered

Contributing

See CONTRIBUTING.md for development guidelines.

This project uses the GSD workflow for structured development. See CLAUDE.md for AI-assisted development patterns.

License

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

Acknowledgments

Design philosophy inspired by The Hitchhiker's Guide to the Galaxy
Built with GSD workflow for efficient solo development
Powered by Claude AI for weekly insights and automation

Built with care for homeschooling families.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.claude		.claude
.github/workflows		.github/workflows
apps		apps
docker		docker
docs		docs
packages		packages
scripts		scripts
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PROJECT_STATUS_EXECUTIVE.md		PROJECT_STATUS_EXECUTIVE.md
PROJECT_STATUS_TECHNICAL.md		PROJECT_STATUS_TECHNICAL.md
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

The Homeschool Guide

Table of Contents

Features

Core Functionality

Cross-Device Experience

Architecture

Data Flow (Offline-First)

Quick Start

Prerequisites

Installation

Access Points

Development

Common Commands

Database Commands

Docker Commands

Project Structure

Technology Stack

Frontend

Backend

DevOps

Testing

Test Commands

Coverage Targets

Deployment

Target Environment

Production Build

Roadmap

Keyboard Shortcuts

Global (Desktop Only)

Activity Log Page

Dashboard Page

Planning Page

Troubleshooting

Common Issues

Database Connection Failed

Service Worker Not Updating

Offline Sync Issues

PWA Not Installing

Contributing

License

Acknowledgments

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages