Skip to content

Commit f7fa4bf

Browse files
tknkaatknkaa
committed
create CLAUDE.md
1 parent 4d60966 commit f7fa4bf

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎CLAUDE.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Hitori Mahjong - Project Architecture & Documentation
2+
3+
This document provides a comprehensive analysis of the Hitori Mahjong web application, detailing its architecture, technology choices, and development practices.
4+
5+
## Project Overview
6+
7+
Hitori Mahjong is a modern web application that implements a single-player version of Mahjong. The project demonstrates a full-stack approach using cutting-edge web technologies with a focus on performance, developer experience, and scalability.
8+
9+
## Architecture Philosophy
10+
11+
The application follows a **full-stack React** approach, leveraging React Router v7's capabilities for both client-side and server-side rendering. This unified approach provides:
12+
13+
- **Code sharing** between client and server
14+
- **Type safety** throughout the entire stack
15+
- **Performance optimization** through SSR and edge deployment
16+
- **Developer experience** with hot reloading and modern tooling
17+
18+
## Technology Stack
19+
20+
### Core Framework
21+
- **React Router v7**: Serves as both the frontend framework and backend runtime
22+
- **Vite**: Build tool and development server
23+
- **TypeScript**: Primary language for type safety and developer experience
24+
25+
### Runtime & Deployment
26+
- **Cloudflare Workers**: Edge runtime for serverless deployment
27+
- **Bun**: Package manager and JavaScript runtime for development
28+
29+
### Data Layer
30+
- **Drizzle ORM**: Type-safe database interactions
31+
- **Better Auth**: Authentication and session management
32+
- **Redis**: Caching and session storage
33+
34+
### Styling & UI
35+
- **Tailwind CSS**: Utility-first CSS framework
36+
- **daisyUI**: Component library built on Tailwind
37+
38+
### Development Tools
39+
- **Biome**: Fast linter and formatter
40+
- **Lefthook**: Git hooks for code quality
41+
- **Docker Compose**: Local development environment
42+
43+
## Directory Structure Analysis
44+
45+
### `/app` - Application Core
46+
The heart of the application, following React Router v7 conventions:
47+
48+
```
49+
app/
50+
├── root.tsx # Root application component
51+
├── entry.server.tsx # SSR entry point
52+
├── routes/ # File-based routing
53+
│ ├── _index.tsx # Home page
54+
│ ├── learn.tsx # Tutorial/learning interface
55+
│ └── api.auth.$.ts # Authentication API endpoints
56+
└── lib/ # Core business logic
57+
├── auth.ts # Server-side auth logic
58+
├── auth-client.ts # Client-side auth utilities
59+
├── hai.ts # Mahjong tile logic (牌)
60+
├── redis.ts # Cache layer
61+
├── db/ # Database layer
62+
└── components/ # Reusable UI components
63+
```
64+
65+
### `/public` - Static Assets
66+
Organized by feature with Mahjong-specific assets:
67+
68+
```
69+
public/
70+
├── hai/ # Mahjong tile images (牌)
71+
├── tutorial/ # Educational content assets
72+
├── background/ # UI background images
73+
├── favicon.ico # Browser icon
74+
└── logo.svg # Application branding
75+
```
76+
77+
### `/workers` - Edge Runtime
78+
Contains the Cloudflare Worker that serves the application at the edge.
79+
80+
## Key Design Decisions
81+
82+
### 1. Full-Stack React Architecture
83+
- **Rationale**: Unified development experience with shared code between client and server
84+
- **Benefits**: Type safety, reduced context switching, better performance through SSR
85+
- **Trade-offs**: Learning curve for developers new to full-stack React
86+
87+
### 2. Edge-First Deployment
88+
- **Rationale**: Global performance and reduced latency
89+
- **Benefits**: Fast response times worldwide, automatic scaling
90+
- **Trade-offs**: Runtime limitations of edge environments
91+
92+
### 3. File-Based Routing
93+
- **Rationale**: Convention over configuration, reduced boilerplate
94+
- **Benefits**: Intuitive project structure, automatic route generation
95+
- **Trade-offs**: Less flexibility for complex routing patterns
96+
97+
### 4. Type-Safe Database Layer
98+
- **Rationale**: Prevent runtime errors, improve developer experience
99+
- **Benefits**: Compile-time checks, better refactoring support, IntelliSense
100+
- **Trade-offs**: Additional build-time complexity
101+
102+
## Development Workflow
103+
104+
### Local Development
105+
1. **Environment Setup**: Docker Compose provides local services (likely database/Redis)
106+
2. **Development Server**: Vite provides fast HMR and development experience
107+
3. **Code Quality**: Biome handles linting and formatting
108+
4. **Git Hooks**: Lefthook ensures code quality before commits
109+
110+
### Deployment Pipeline
111+
1. **CI/CD**: GitHub Actions handle automated testing and deployment
112+
2. **Edge Deployment**: Wrangler deploys to Cloudflare Workers
113+
3. **Database Migrations**: Drizzle handles schema changes
114+
115+
## Performance Considerations
116+
117+
### Client-Side Optimizations
118+
- **Code Splitting**: Route-based chunking through React Router
119+
- **Asset Optimization**: Vite handles bundling and minification
120+
- **Caching**: Strategic use of Redis for frequently accessed data
121+
122+
### Server-Side Optimizations
123+
- **SSR**: Faster initial page loads and better SEO
124+
- **Edge Deployment**: Reduced latency through global distribution
125+
- **Database Queries**: Type-safe, optimized queries through Drizzle
126+
127+
## Security Features
128+
129+
### Authentication
130+
- **Better Auth**: Modern, secure authentication system
131+
- **Session Management**: Secure session handling with Redis backing
132+
- **API Protection**: Authentication middleware for protected routes
133+
134+
### Data Security
135+
- **Type Safety**: Prevents many classes of runtime errors
136+
- **Input Validation**: Handled through TypeScript interfaces and runtime checks
137+
- **Environment Variables**: Secure configuration management
138+
139+
## Mahjong-Specific Implementation
140+
141+
### Tile System (`hai.ts`)
142+
The core game logic is encapsulated in the `hai.ts` module, handling:
143+
- Tile representation and validation
144+
- Game state management
145+
- Scoring algorithms
146+
- Rule enforcement
147+
148+
### Visual Assets
149+
- **Tile Images**: Complete set of Mahjong tile graphics in `/public/hai/`
150+
- **Tutorial Graphics**: Educational materials in `/public/tutorial/`
151+
- **Responsive Design**: Tailwind CSS ensures mobile-friendly gameplay
152+
153+
## Future Considerations
154+
155+
### Scalability
156+
- **Database**: Current setup supports horizontal scaling through Cloudflare D1
157+
- **Caching**: Redis layer can be expanded for complex caching strategies
158+
- **CDN**: Static assets benefit from Cloudflare's global CDN
159+
160+
### Feature Expansion
161+
- **Multiplayer Support**: Architecture supports WebSocket integration for real-time gameplay
162+
- **Analytics**: Event tracking can be added through the existing API layer
163+
- **Internationalization**: React Router v7 supports i18n out of the box
164+
165+
## Maintenance & Operations
166+
167+
### Monitoring
168+
- **Error Tracking**: Can be integrated through Cloudflare Workers analytics
169+
- **Performance Monitoring**: Built-in metrics through Cloudflare dashboard
170+
- **Uptime**: Edge deployment provides inherent high availability
171+
172+
### Updates & Maintenance
173+
- **Dependency Management**: Bun provides fast, reliable package management
174+
- **Database Migrations**: Drizzle provides safe, versioned schema changes
175+
- **Rollback Strategy**: Cloudflare Workers support instant rollbacks
176+
177+
## Conclusion
178+
179+
This project represents a modern, well-architected web application that leverages the latest in web development practices. The choice of React Router v7 as a full-stack framework, combined with edge deployment through Cloudflare Workers, provides an excellent foundation for a performant, scalable Mahjong game.
180+
181+
The clean separation of concerns, type safety throughout the stack, and thoughtful tooling choices create a maintainable codebase that can evolve with changing requirements while providing an excellent user experience.

0 commit comments

Comments
 (0)