165 lines
4.5 KiB
Markdown
165 lines
4.5 KiB
Markdown
# AGENTS.md - Guidelines for Agentic Coding
|
|
|
|
## Project Overview
|
|
|
|
This is a simple Flask web application - a "Jeopardy-style" quiz game about the Russian short story "Уроки французского" by Valentin Rasputin. The project uses:
|
|
- **Backend**: Python 3.13 with Flask
|
|
- **Frontend**: HTML, CSS, JavaScript (vanilla)
|
|
- **Data Storage**: JSON file (`data/questions.json`)
|
|
- **State**: Browser localStorage (client-side)
|
|
|
|
## Build/Test Commands
|
|
|
|
### Running the Application
|
|
|
|
```bash
|
|
# Activate virtual environment
|
|
source venv/bin/activate
|
|
|
|
# Run Flask app (default port 5000)
|
|
python app.py
|
|
|
|
# Run on specific port
|
|
python -c "from app import app; app.run(port=5002)"
|
|
```
|
|
|
|
### No Formal Tests
|
|
|
|
This project does not have a formal test suite. For manual testing:
|
|
- Use `curl` to test API endpoints
|
|
- Test in browser at http://localhost:5000 (or configured port)
|
|
|
|
### Linting/Type Checking
|
|
|
|
No formal linter is configured. The codebase uses basic Python and JavaScript.
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Python (app.py)
|
|
|
|
**Imports**
|
|
- Standard library first, then third-party
|
|
- Use absolute imports
|
|
- Example:
|
|
```python
|
|
import json
|
|
from flask import Flask, render_template, request, redirect, url_for, make_response
|
|
```
|
|
|
|
**Formatting**
|
|
- Use 4 spaces for indentation
|
|
- Maximum line length: 100 characters
|
|
- Blank lines: 2 between top-level definitions, 1 between function definitions
|
|
|
|
**Naming Conventions**
|
|
- `snake_case` for variables, functions
|
|
- `PascalCase` for classes
|
|
- `UPPER_SNAKE_CASE` for constants
|
|
|
|
**Error Handling**
|
|
- Use try/except for file operations (JSON loading/saving)
|
|
- Return proper HTTP error codes (400, 404, 500)
|
|
- Log errors to console
|
|
|
|
**Flask-Specific**
|
|
- Use `app.secret_key` for sessions
|
|
- Always use `ensure_ascii=False` with JSON for Cyrillic support
|
|
- Use `context_processor` for global template variables
|
|
|
|
### JavaScript (templates/*.html)
|
|
|
|
**General**
|
|
- Use vanilla JavaScript (no frameworks)
|
|
- Prefer `var` over `let/const` for compatibility
|
|
- Use `function` keyword instead of arrow functions where possible
|
|
|
|
**Event Handling**
|
|
- Use `onclick` directly in HTML or `element.onclick = function()`
|
|
- Avoid `addEventListener` for simplicity
|
|
|
|
**DOM Manipulation**
|
|
- Use `document.getElementById` and `document.querySelector`
|
|
- Template literals for dynamic content: `` `string ${variable}` ``
|
|
- Use `JSON.parse()` and `JSON.stringify()` for localStorage
|
|
|
|
**Naming**
|
|
- camelCase for variables and functions
|
|
- Descriptive names (e.g., `currentTeam`, `selectAnswer`)
|
|
|
|
### HTML/CSS (templates/*.html)
|
|
|
|
**Template Syntax (Jinja2)**
|
|
- Use `{% for %}` loops with `enumerate()` for indexed iteration
|
|
- Pass data via `{{ variable }}` syntax
|
|
- Use `|tojson` filter for JavaScript data
|
|
|
|
**CSS**
|
|
- Use CSS custom properties (variables) for colors
|
|
- Follow BEM-like naming for classes
|
|
- Keep responsive design in mind
|
|
|
|
**Structure**
|
|
- Inline CSS in `<style>` tags (simple project)
|
|
- Inline JS in `<script>` tags at end of body
|
|
|
|
## File Organization
|
|
|
|
```
|
|
/home/eof/dev/roma/sigra/
|
|
├── app.py # Flask application
|
|
├── data/
|
|
│ └── questions.json # Game questions data
|
|
├── templates/
|
|
│ ├── index.html # Main game page
|
|
│ ├── admin.html # Admin panel (edit questions)
|
|
│ ├── edit.html # Question editor
|
|
│ └── login.html # Admin login
|
|
├── static/ # Static assets (empty currently)
|
|
├── venv/ # Virtual environment
|
|
├── SPEC.md # Project specification
|
|
└── AGENTS.md # This file
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Adding a New Question
|
|
1. Edit `data/questions.json` manually or via admin panel at `/admin`
|
|
2. Follow existing structure:
|
|
```json
|
|
{
|
|
"cost": 600,
|
|
"question": "Question text?",
|
|
"options": ["Option 1", "Option 2", "Option 3", "Option 4"],
|
|
"answer": 0 // 0-3 index of correct answer
|
|
}
|
|
```
|
|
|
|
### Adding a New Route
|
|
1. Add route in `app.py` using `@app.route()`
|
|
2. Return `render_template()` or `jsonify()`
|
|
3. For API routes, use proper HTTP methods
|
|
|
|
### Modifying Game Logic
|
|
- Game state stored in browser's localStorage
|
|
- Key: `francuzskiy_game`
|
|
- Structure: `{ score: 0, answered: [], userAnswers: {}, teams: [] }`
|
|
|
|
## Security Notes
|
|
|
|
- Admin panel is password-protected (password in `app.py`)
|
|
- No database - data is in JSON file
|
|
- No SQL injection risk (no database)
|
|
- XSS: Be careful with `innerHTML` - user input in questions is trusted
|
|
|
|
## Dependencies
|
|
|
|
```
|
|
Flask==3.1.3
|
|
Jinja2==3.1.6
|
|
Werkzeug==3.1.6
|
|
```
|
|
|
|
## Contact
|
|
|
|
For questions about this codebase, refer to SPEC.md or the original requirements.
|