sigra/AGENTS.md

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

# 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:

  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:

   {
       "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.