Skip to content

Commit dbb0f2a

Browse files
YilingCAIYilingCAI
committed
add fraontend readme
1 parent df209f3 commit dbb0f2a

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎frontend/README_ANGULAR.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Frontend - Angular (Tic Tac Toe Game)
2+
3+
This is the Angular implementation of the Tic Tac Toe game frontend, refactored from React/Next.js.
4+
5+
## Technology Stack
6+
7+
- **Framework**: Angular 19
8+
- **Language**: TypeScript 5.6
9+
- **Styling**: Tailwind CSS 4
10+
- **HTTP Client**: Angular HttpClient
11+
- **Routing**: Angular Router
12+
- **State Management**: RxJS with Services and Observables
13+
- **Testing**: Jasmine & Karma
14+
- **Build Tool**: Angular CLI
15+
16+
## Prerequisites
17+
18+
- Node.js 18+ (or use nvm)
19+
- npm or yarn
20+
21+
### Install Node.js with nvm (Optional)
22+
23+
```bash
24+
# Install nvm
25+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
26+
export NVM_DIR="$HOME/.nvm"
27+
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
28+
29+
# Install Node.js LTS
30+
nvm install --lts
31+
nvm use --lts
32+
node -v # Node.js version, e.g., v20.x.x
33+
npm -v # npm version, e.g., 10.x.x
34+
```
35+
36+
## Setup
37+
38+
### Installation
39+
40+
```bash
41+
npm install
42+
```
43+
44+
### Development Server
45+
46+
```bash
47+
npm start
48+
```
49+
50+
Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
51+
52+
### Build
53+
54+
```bash
55+
npm run build
56+
```
57+
58+
The build artifacts will be stored in the `dist/` directory.
59+
60+
### Running Tests
61+
62+
```bash
63+
npm test
64+
```
65+
66+
### Linting
67+
68+
```bash
69+
npm run lint
70+
npm run lint:fix
71+
```
72+
73+
## Project Structure
74+
75+
```
76+
src/
77+
├── app/
78+
│ ├── components/ # Angular components
79+
│ │ ├── login/
80+
│ │ ├── signup/
81+
│ │ ├── homepage/
82+
│ │ ├── game-board/
83+
│ │ ├── create-game/
84+
│ │ └── join-game/
85+
│ ├── services/ # Services (API, Auth, Game)
86+
│ ├── core/ # Core functionality (guards, interceptors)
87+
│ ├── types/ # TypeScript interfaces
88+
│ ├── app.component.ts # Root component
89+
│ ├── app.routes.ts # Route configuration
90+
│ └── app.module.ts # App module
91+
├── environments/ # Environment configuration
92+
├── index.html # HTML entry point
93+
├── main.ts # Bootstrap file
94+
├── polyfills.ts # Browser polyfills
95+
└── styles.css # Global styles
96+
```
97+
98+
## Key Features
99+
100+
### Authentication
101+
- User registration and login
102+
- JWT token-based authentication
103+
- Automatic token refresh via interceptors
104+
- Protected routes with AuthGuard
105+
106+
### Game Features
107+
- Create new tic-tac-toe games
108+
- Join existing games by game ID
109+
- Real-time move updates
110+
- Game state management
111+
- Win/loss tracking
112+
113+
### Architecture
114+
- **Standalone Components**: Modern Angular with standalone components
115+
- **Dependency Injection**: Services for API, Auth, and Game logic
116+
- **HTTP Interceptors**: Automatic token injection and error handling
117+
- **Reactive Programming**: RxJS observables for state management
118+
- **Type Safety**: Full TypeScript with strict mode
119+
120+
## API Integration
121+
122+
The frontend integrates with the backend API at `http://localhost:8000`:
123+
124+
### Authentication Endpoints
125+
- `POST /users/register` - Register new user
126+
- `POST /users/login` - User login
127+
- `GET /users/me` - Get current user profile
128+
129+
### Game Endpoints
130+
- `POST /games/create_game` - Create new game
131+
- `POST /games/{game_id}/join` - Join existing game
132+
- `POST /games/move` - Make a move
133+
- `GET /games` - Get user's games
134+
- `GET /games/{game_id}` - Get specific game
135+
136+
## Configuration
137+
138+
### Environment Variables
139+
140+
Create a `.env.local` file in the frontend directory:
141+
142+
```
143+
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
144+
```
145+
146+
## Docker
147+
148+
Build and run the frontend in Docker:
149+
150+
```bash
151+
# Build
152+
docker build -t tic-tac-toe-frontend .
153+
154+
# Run
155+
docker run -p 4200:4200 \
156+
-e NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 \
157+
tic-tac-toe-frontend
158+
```
159+
160+
## Component Documentation
161+
162+
See [ANGULAR_MIGRATION.md](./ANGULAR_MIGRATION.md) for detailed architecture and component documentation.
163+
164+
## Deployment
165+
166+
### Development
167+
```bash
168+
npm start
169+
```
170+
171+
### Production
172+
```bash
173+
npm run build
174+
# Serve the dist/frontend directory
175+
```
176+
177+
## Troubleshooting
178+
179+
### Port already in use
180+
```bash
181+
# Change the default port in angular.json or use:
182+
ng serve --port 4300
183+
```
184+
185+
### API connection issues
186+
- Ensure the backend is running on `http://localhost:8000`
187+
- Check `environment.ts` for correct API URL
188+
- Verify CORS settings on the backend
189+
190+
### Build errors
191+
```bash
192+
# Clear cache and reinstall
193+
rm -rf node_modules dist
194+
npm install
195+
npm run build
196+
```
197+
198+
## Migration Notes
199+
200+
This project was migrated from React/Next.js to Angular with the following improvements:
201+
- Stronger type safety with Angular's TypeScript implementation
202+
- Better state management with RxJS and Services
203+
- Built-in dependency injection
204+
- Enhanced routing with guards
205+
- Better testing infrastructure with Jasmine/Karma
206+
- Improved component lifecycle management
207+
208+
## Support & Documentation
209+
210+
- [Angular Documentation](https://angular.io/docs)
211+
- [Angular CLI Documentation](https://angular.io/cli)
212+
- [RxJS Documentation](https://rxjs.dev)
213+
- [Tailwind CSS Documentation](https://tailwindcss.com)

0 commit comments

Comments
 (0)