A comprehensive web application for managing homeschool programs, supporting multiple students with attendance tracking, lesson planning, assignments, and grading. Designed to help ease the administrative burden of your homeschool program and improve the accuracy of mandatory reporting.
Just in time for the Fall Semester I'm releasing this as an alpha for those who want to test and use it. I find that it already works great for the needs of our program. We use it daily to record and review our progress, but I am sure there will need to be changes as we proceed through the year. I will do my best to keep the database schema as stable as possible, but I can't guarantee there won't be breaking changes yet. (Use the built in system export to take regular backups!)
Once I've completed our first academic term I plan to release a more stable beta in January 2026. Then by summer 2026 I will feel confident enough for a stable release in time for the 2026-2027 school year.
- Multi-user Authentication: Separate logins for parents (administrators) and students
- Attendance Tracking: Record daily attendance with notes and status. Flexibile academic terms to support reporting needs of your jurisdiction.
- Lesson Planning: Organize lessons by subject with scheduling and materials
- Assignment Management: Create, track, and grade various types of assignments
- Optional Gamification: As assignments are graded, student points accumulate to be used as an incentive system (Points system can be disabled in Admin Center)
- Import/Export System: Assignments and Lesson Plans can be exported to simple JSON files for import by other OurSchool installations. Help your fellow homeschool families by sharing.
- Integration API: API can be accessed by external systems for Integration and Automation
git clone [email protected]:DGAzr/ourschool.git
cd ourschool
cp env.EXAMPLE .env
(!!!EDIT YOUR .env FILE TO SUIT YOUR ENVIRONMENT!!!)
bash docker-deploy.sh
Point your browser at localhost:4173
I really, really like coffee :)
- Python 3.8+
- Node.js 16+
- PostgreSQL
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\\Scripts\\activate- Install dependencies:
pip install -r requirements.txt- Set up environment variables:
cp .env.example .env
# Edit .env with your database credentials and secret key-
Database Initialization (First Time Setup):
a. Create the PostgreSQL database:
# Connect to PostgreSQL as superuser sudo -u postgres psql # Create database and user CREATE DATABASE ourschool; CREATE USER postgres WITH PASSWORD 'your-secure-password-here'; GRANT ALL PRIVILEGES ON DATABASE ourschool TO postgres; \q
b. Update your
.envfile with the correct database credentials:POSTGRES_DB=ourschool POSTGRES_USER=postgres POSTGRES_PASSWORD=your-secure-password-here DATABASE_URL=postgresql+psycopg://postgres:your-secure-password-here@localhost:5432/ourschool
-
Run database migrations:
alembic upgrade head- Seed the database with initial admin:
python seed_data.pyThis creates:
- Admin user:
admin/admin123
- Start the API server:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000- Navigate to frontend directory:
cd frontend- Install dependencies:
npm install- Start the development server:
npm run devThe application will be available at:
- Frontend: http://localhost:3000
- API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
OurSchool provides a comprehensive REST API for external integrations, supporting both user session authentication (Bearer tokens) and API key authentication for automated systems.
- Create API Key: Navigate to Admin → API Keys in the web interface
- Set Permissions: Assign required permissions (e.g.,
points:read,assignments:grade) - Secure Storage: Store your API key securely - it starts with
os_
# Login to get token
curl -X POST "http://localhost:8000/api/auth/login" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=admin&password=admin123"
# Use token in requests
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
"http://localhost:8000/api/points/admin/overview"curl -H "X-API-Key: os_YOUR_API_KEY_HERE" \
"http://localhost:8000/api/points/admin/overview"curl -X GET "http://localhost:8000/api/points/admin/overview" \
-H "X-API-Key: os_YOUR_API_KEY_HERE" \
-H "Content-Type: application/json"Response:
{
"total_students_with_points": 2,
"total_students": 2,
"total_points_awarded": 800,
"total_points_spent": 0,
"student_points": [
{
"current_balance": 500,
"total_earned": 500,
"total_spent": 0,
"student_id": 4,
"student_name": "Student One"
},
{
"current_balance": 300,
"total_earned": 300,
"total_spent": 0,
"student_id": 5,
"student_name": "Student Two"
}
]
}curl -X POST "http://localhost:8000/api/integrations/assignments/123/grade" \
-H "X-API-Key: os_YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"points_earned": 85.0,
"teacher_feedback": "Good work! Minor areas for improvement.",
"letter_grade": "B+"
}'curl -X GET "http://localhost:8000/api/points/student/4/balance" \
-H "X-API-Key: os_YOUR_API_KEY_HERE"See list_student_points.py for a complete Python example:
import requests
import os
BASE_URL = "http://localhost:8000"
API_KEY = os.getenv("OURSCHOOL_API_KEY")
headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
}
# Get all student points
response = requests.get(f"{BASE_URL}/api/points/admin/overview", headers=headers)
if response.status_code == 200:
data = response.json()
for student in data['student_points']:
print(f"{student['student_name']}: {student['current_balance']} points")POST /api/auth/login- User authentication (returns JWT)
GET /api/users/me- Current user profile (session auth only)
GET /api/points/admin/overview- All student points overviewGET /api/points/student/{id}/balance- Individual student pointsGET /api/points/student/{id}/ledger- Student transaction historyPOST /api/points/adjust- Manually adjust student points
GET /api/integrations/assignments/{id}- Get assignment detailsPOST /api/integrations/assignments/{id}/grade- Grade assignment
POST /api/attendance/- Record attendanceGET /api/lessons/- List lessons with filteringPOST /api/assignments/- Create assignments (session auth)
| Permission | Description |
|---|---|
points:read |
Read student points and transaction history |
points:write |
Adjust student points |
assignments:read |
Read assignment data |
assignments:grade |
Grade student assignments |
students:read |
Read student information |
attendance:read |
Read attendance records |
attendance:write |
Record attendance |
Create a new migration:
alembic revision --autogenerate -m "Description"Apply migrations:
alembic upgrade headBackend tests:
pytestFrontend tests:
cd frontend && npm test- FastAPI - Modern Python web framework
- SQLAlchemy - Database ORM with PostgreSQL support
- Alembic - Database migrations
- JWT Authentication - Secure token-based auth
- Pydantic - Data validation and serialization
- React 18 - Modern UI library
- TypeScript - Type-safe JavaScript
- Tailwind CSS - Utility-first CSS framework
- React Router - Client-side routing
- React Query - Server state management
- Vite - Fast build tool
The application can be deployed using Docker, traditional hosting, or cloud platforms. Ensure proper environment variables are set for production use.
This project is licensed under the GNU Affero General Public License v3 (GNU AGPLv3).
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.