- Python 58.5%
- TypeScript 35%
- CSS 5.4%
- Shell 0.7%
- JavaScript 0.2%
- Other 0.2%
| .agents/skills | ||
| .forgejo/workflows | ||
| app | ||
| content_images | ||
| docs | ||
| frontend | ||
| scripts | ||
| tests | ||
| .dockerignore | ||
| .env.example | ||
| .env.prod | ||
| .env.test | ||
| .gitignore | ||
| AGENTS.md | ||
| ARCHITECTURE.md | ||
| brand-guidelines.skill | ||
| docker-compose.prod.yml | ||
| docker-compose.test.yml | ||
| docker-compose.yml | ||
| DOCKER_DEPLOYMENT_GUIDE.md | ||
| Dockerfile | ||
| DOCUMENTATION_INDEX.md | ||
| DOCUMENTATION_UPDATES.md | ||
| entrypoint.sh | ||
| main.py | ||
| memory.md | ||
| public-doc-updater.skill | ||
| pytest.ini | ||
| README.md | ||
| requirements.txt | ||
Honbu Manager - Karate Club Management System
Status: ✅ Production Ready | 
| 
🔐 Security: ✅ All API endpoints authenticated with JWT | ✅ Strict role-based & tenant-isolated access control 📊 Database: ✅ PostgreSQL with proper migrations 💻 Frontend: ✅ Modern React 18 SPA with Vite & TipTap CMS integration
Quick Start (Docker)
git clone <repository-url>
cd club-manager
docker-compose up -d --build
Open: http://localhost:5000
Default Login: admin / AdminPassword123 (⚠️ Change immediately!)
Manual Setup (Development)
Requires two terminal tabs:
Tab 1: Backend
pip install -r requirements.txt
python main.py
Tab 2: Frontend
cd frontend
npm install
npm run dev
Quick Links to Documentation
| Purpose | Document |
|---|---|
| Get Started (2 min) | 📘 QUICK_START.md |
| System Architecture | 🏗️ ARCHITECTURE.md |
| Frontend Dev Guide | 💻 docs/FRONTEND_ARCHITECTURE.md |
| User Guide | 👤 docs/FRONTEND_GUIDE.md |
| Deploy to Production | 🐳 docs/DEPLOYMENT_GUIDE.md |
| Docker & Build Guide | 🐳 docs/DOCKER_BUILD_GUIDE.md |
| Security Best Practices | 🔒 docs/SECURITY_GUIDE.md |
| Troubleshooting | 🔧 docs/TROUBLESHOOTING.md |
| Full Index | 📇 docs/INDEX.md |
Testing
379 backend tests passing | 84 frontend tests passing
Tests run automatically on every push via Forgejo CI. See .forgejo/workflows/ci.yml.
Backend Tests (pytest)
# Run locally with Docker
docker-compose -f docker-compose.yml -f docker-compose.test.yml up -d
docker exec honbu-manager python3 -m pytest tests/unit/ tests/e2e/controllers/ -v
Frontend Tests (vitest)
cd frontend
npm run test
Overview
Comprehensive karate club management application with member tracking, class management, attendance tracking, and content publishing.
Key Features
- 👥 Member Management - Add, edit, manage members and families
- 📊 Attendance Tracking - Track class attendance with robust statistics
- 🥋 Belt Progression - Manage belt levels and grading records
- 🏢 Multi-Club Support - True tenant isolation for multiple clubs
- 📝 Content Publishing - Built-in CMS for rich text Pages and Blog Posts (TipTap)
- 🔌 REST API - Full Swagger documentation
- 📱 PWA Ready - Installable web application for iOS/Android
Architecture Highlights
app/ ← Python Backend (Flask RESTX, C.O.R.E. Architecture)
frontend/ ← React SPA (Vite, TypeScript, React Router)
tests/ ← Pytest and Vitest suites
docs/ ← Comprehensive documentation
See ARCHITECTURE.md for full details.
Tech Stack
- Backend: Python 3.13, Flask, Flask-RESTX
- Frontend: React 18, TypeScript, Vite, DOMPurify
- Database: PostgreSQL
- Testing: pytest, vitest, Playwright
- Container: Docker & Docker Compose
API Docs
When running locally: Swagger UI: http://localhost:5000/api/docs ReDoc: http://localhost:5000/api/redoc
Version
v2.0 - May 2026 | Production Ready ✅
📖 Full documentation: See docs/INDEX.md