86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# Soroban Web Application
|
|
|
|
Interactive web application for learning soroban (Japanese abacus) calculation with tutorials, practice sessions, and multiplayer arcade games.
|
|
|
|
## Features
|
|
|
|
- **Tutorials** - Step-by-step lessons for learning soroban techniques
|
|
- **Practice Sessions** - Adaptive practice with progressive help system
|
|
- **Arcade Games** - Multiplayer educational games for reinforcement
|
|
- **Worksheet Generator** - Create printable math worksheets
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Start development server
|
|
pnpm dev
|
|
|
|
# Run type checks
|
|
npm run type-check
|
|
|
|
# Run all quality checks
|
|
npm run pre-commit
|
|
```
|
|
|
|
## Documentation
|
|
|
|
### Components
|
|
|
|
| Component | Description |
|
|
| ----------------------------------------------------------------- | ---------------------------------------------------- |
|
|
| [Decomposition Display](./src/components/decomposition/README.md) | Interactive mathematical decomposition visualization |
|
|
| [Worksheet Generator](./src/app/create/worksheets/README.md) | Math worksheet creation with Typst PDF generation |
|
|
|
|
### Games
|
|
|
|
| Game | Description |
|
|
| --------------------------------------------------------------- | ------------------------------------- |
|
|
| [Arcade System](./src/arcade-games/README.md) | Modular multiplayer game architecture |
|
|
| [Know Your World](./src/arcade-games/know-your-world/README.md) | Geography quiz game |
|
|
|
|
### Developer Documentation
|
|
|
|
Located in `.claude/` directory:
|
|
|
|
- `CLAUDE.md` - Project conventions and guidelines
|
|
- `CODE_QUALITY_REGIME.md` - Quality check procedures
|
|
- `GAME_SETTINGS_PERSISTENCE.md` - Game config architecture
|
|
- `Z_INDEX_MANAGEMENT.md` - Z-index layering system
|
|
- `DEPLOYMENT.md` - Deployment and CI/CD
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/web/
|
|
├── src/
|
|
│ ├── app/ # Next.js App Router pages
|
|
│ ├── components/ # Shared React components
|
|
│ │ ├── decomposition/ # Math decomposition display
|
|
│ │ ├── practice/ # Practice session components
|
|
│ │ └── tutorial/ # Tutorial player components
|
|
│ ├── contexts/ # React context providers
|
|
│ ├── arcade-games/ # Multiplayer game implementations
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── lib/ # Utilities and libraries
|
|
│ └── db/ # Database schema and queries
|
|
├── .claude/ # Developer documentation
|
|
├── public/ # Static assets
|
|
└── styled-system/ # Generated Panda CSS
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
- **Framework**: Next.js 14 (App Router)
|
|
- **Language**: TypeScript
|
|
- **Styling**: Panda CSS
|
|
- **Database**: SQLite with Drizzle ORM
|
|
- **Abacus Visualization**: @soroban/abacus-react
|
|
|
|
## Related Documentation
|
|
|
|
**Parent**: [Main README](../../README.md) - Complete project overview
|
|
**Abacus Component**: [packages/abacus-react](../../packages/abacus-react/README.md) - Abacus visualization library
|