Skip to content

Commit 55e131b

Browse files
anhtrannamtuananhtrannamtuan
committed
docs: Add workspace instructions for Soc Ops development
1 parent 60ac264 commit 55e131b

1 file changed

Lines changed: 130 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Soc Ops — Workspace Instructions
2+
3+
**Social Bingo game** for in-person mixers. This is a FastAPI + HTMX web application with real-time interactions and cookie-based session management.
4+
5+
---
6+
7+
## Code Style & Formatting
8+
9+
- **Python**: Python 3.13+, PEP 8 via `ruff`. Line length: 88 characters.
10+
- **Imports**: Sorted alphabetically with `ruff` (`E`, `F`, `I`, `N`, `W` rules enabled).
11+
- **Type Hints**: Use `@pydantic.BaseModel` for request/response schemas. Add type hints to function signatures.
12+
- **Naming**: `snake_case` for functions/variables, `snake_case` for template files, `PascalCase` for classes.
13+
14+
Run linting and formatting before requesting review:
15+
`ash
16+
python -m uv run ruff check .
17+
python -m uv run ruff format .
18+
`
19+
20+
---
21+
22+
## Architecture
23+
24+
The application follows a **layered FastAPI structure**:
25+
26+
- **`app/main.py`**: FastAPI app initialization, routes, middleware (session management via `SessionMiddleware`)
27+
- **`app/game_service.py`**: Game session management, player state, game logic orchestration
28+
- **`app/game_logic.py`**: Core bingo game rules (board generation, winning conditions, square toggling)
29+
- **`app/models.py`**: Pydantic models for data validation (`GameState`, `Square`, etc.)
30+
- **`app/templates/`**: Jinja2 HTML templates with HTMX directives for real-time interactions
31+
- **`app/static/css/app.css`**: Custom utility classes (Tailwind-like, not actual Tailwind)
32+
33+
### Key Patterns
34+
35+
- **Session Management**: Cookie-based sessions with `SessionMiddleware`. Session ID stored in `request.session["session_id"]`.
36+
- **HTMX Integration**: Real-time game updates without page reloads. Routes return HTML fragments for partial page updates.
37+
- **Template Structure**: Base template in `base.html` with component templates in `components/` for reusability.
38+
- **No State Database**: Game state is stored in-memory via `GameSession` objects. Not persisted across server restarts.
39+
40+
---
41+
42+
## Build & Test
43+
44+
### Setup Dependencies
45+
`ash
46+
python -m uv sync
47+
`
48+
49+
### Run Development Server
50+
`ash
51+
python -m uv run uvicorn app.main:app --reload --port 8000
52+
`
53+
Then open `http://localhost:8000` in your browser (not VS Code Simple Browser).
54+
55+
### Run Tests
56+
`ash
57+
python -m uv run pytest
58+
`
59+
Test coverage: API endpoints (`test_api.py`) and game logic (`test_game_logic.py`).
60+
61+
### Linting & Formatting
62+
`ash
63+
python -m uv run ruff check . # Check linting errors
64+
python -m uv run ruff format . # Auto-format code
65+
`
66+
67+
---
68+
69+
## Conventions
70+
71+
### HTML & HTMX
72+
- **HTMX Attributes**: Use `hx-post`, `hx-swap`, `hx-target` for dynamic interactions. Keep HTMX logic in templates, not JavaScript.
73+
- **CSS Classes**: Use custom utility classes from `app.css` (e.g., `flex`, `grid-cols-5`, `p-4`, `mb-2`). Never add inline styles; use utility classes.
74+
- **Template Inheritance**: All templates extend `base.html` with `{% extends "base.html" %}`. Use `{% block content %}` for page-specific content.
75+
76+
### Python
77+
- **Error Handling**: Use Pydantic validation for request data. Let FastAPI handle 422 validation errors.
78+
- **Session Access**: Always call `_get_game_session(request)` to retrieve or create a session from the current request.
79+
- **Database**: Not used. Game state lives in memory via `GameSession` on server—changes are not persisted.
80+
81+
### Testing
82+
- **Unit Tests**: Test game logic in isolation (`test_game_logic.py` — rules, board generation, win conditions).
83+
- **API Tests**: Test HTTP endpoints with `TestClient` (`test_api.py` — status codes, response formats, session management).
84+
- **Fixtures**: Use pytest fixtures for reusable game state and test clients.
85+
86+
---
87+
88+
## When Stuck
89+
90+
1. **Tests fail**: Run `python -m uv run pytest -v` for detailed output. Check `tests/` folder for existing patterns.
91+
2. **Linting errors**: Run `python -m uv run ruff check . --show-fixes` to see fixes, or auto-format with `ruff format .`.
92+
3. **Server won't start**: Ensure port 8000 is free. Check Python version: `python --version` (must be 3.13+).
93+
4. **HTMX not working**: Ensure full browser (not VS Code Simple Browser). Check browser console for errors.
94+
95+
---
96+
97+
## File Organization
98+
99+
`
100+
app/
101+
main.py # FastAPI app, routes, middleware
102+
game_service.py # Session management & orchestration
103+
game_logic.py # Core bingo game rules
104+
models.py # Pydantic models
105+
templates/ # Jinja2 templates
106+
base.html
107+
home.html
108+
components/
109+
bingo_board.html
110+
game_screen.html
111+
start_screen.html
112+
bingo_modal.html
113+
static/
114+
css/app.css # Utility classes
115+
js/htmx.min.js
116+
tests/
117+
test_api.py # API endpoint tests
118+
test_game_logic.py # Game logic unit tests
119+
`
120+
121+
---
122+
123+
## References
124+
125+
- **FastAPI Docs**: https://fastapi.tiangolo.com/
126+
- **HTMX**: https://htmx.org/
127+
- **Jinja2**: https://jinja.palletsprojects.com/
128+
- **Pydantic**: https://docs.pydantic.dev/
129+
- **Uvicorn**: https://www.uvicorn.org/
130+
- **Workshop Guide**: See `workshop/` folder for lab steps and context engineering examples.

0 commit comments

Comments
 (0)