WIP

Author: estyxx

backend/AGENTS.md

@@ -0,0 +1,311 @@
+# `AGENTS.md`
+
+This file provides guidance to AI agents when working with code in this repository.
+
+## Core Architecture
+
+**PyCon Italia** is a comprehensive Django-based conference management platform with:
+
+- **Backend**: Django application managing conferences, submissions, speakers, attendees, and more
+- **Frontend**: Next.js/TypeScript/React application deployed on Vercel
+- **Database**: PostgreSQL
+- **Package Management**: `uv` for Python dependencies, `pnpm` for Node.js dependencies
+- **Testing**: Comprehensive test suite using pytest for backend
+- **CI/CD**: GitHub Actions for continuous integration and builds
+- **Deployment**: Docker containers, infrastructure managed via Terraform
+
+### Repository Structure
+
+- `backend/`: Main Django application code with conference management modules:
+  - `api/`: GraphQL API endpoints
+  - `conferences/`: Conference models and management
+  - `submissions/`: Talk/workshop submission system (CFP)
+  - `schedule/`: Event scheduling and management
+  - `users/`: User authentication and profiles
+  - `participants/`: Attendee management
+  - `sponsors/`: Sponsorship management
+  - `grants/`: Financial assistance system (Finaid)
+  - `billing/`: Payment processing
+  - `cms/`: Content management system
+  - `blog/`: News and announcements
+  - `pages/`: Static page management
+  - `voting/`: Community voting system
+  - `reviews/`: Submission review system (Program Committee)
+  - `badges/`: Digital badge system
+  - `badge_scanner/`: Badge scanning functionality
+  - `notifications/`: Email and notification system
+- `frontend/`: Next.js application with TypeScript and React
+- `association-frontend/`: Association-specific frontend
+- `association-backend/`: Association-specific backend
+- `toolkit/`: Shared utilities and tools
+- `infrastructure/`: Terraform infrastructure configuration
+- `.github/`: GitHub Actions workflows and configuration
+- `eslint-config-pythonit/`: Shared ESLint configuration
+
+## Conference Management Domain Knowledge
+
+### Conference Lifecycle
+
+The PyCon Italia conference follows a well-defined timeline with specific phases:
+
+1. **Pre-Conference Planning** (6-12 months before)
+   - Configure conference settings (deadlines, topics, submission types, languages)
+   - Set up sponsor tiers and packages
+   - Define audience levels and duration options
+
+2. **Call for Proposals (CFP)** (4-6 months before)
+   - Speakers submit talks, workshops, posters
+   - Submission includes: title, abstract, elevator pitch, speaker bio, tags
+   - "Fake deadlines" strategy: announce deadline, then extend by a week for urgency
+
+3. **Community Voting** (after CFP closes)
+   - Eligible voters: proposal submitters, ticket holders, past attendees (last 2 years)
+   - Weighted ranking algorithm prioritizes engaged community members
+   - Eligibility configured via Pretix event IDs
+
+4. **Internal Review** (Program Committee)
+   - Numeric scoring system (0=No, 1=Maybe, 2=Yes)
+   - Random proposal ordering to reduce bias
+   - Tag-based filtering for reviewer expertise
+   - Proposals sorted by cumulative scores
+
+5. **Schedule Building**
+   - Excel draft with session allocation
+   - Django admin schedule builder interface
+   - Room configuration and day planning
+   - Keynote speaker selection (community + sponsor slots)
+
+6. **Financial Aid (Finaid) Process**
+   - Concurrent with CFP opening
+   - Multiple grant types: Ticket, Travel, Accommodation
+   - Committee evaluation with scoring system
+   - Status workflow: Pending → Approved/Rejected → Confirmed
+
+### Key Domain Concepts
+
+#### Submission System
+- **Types**: Talk, Workshop, Poster, Keynote
+- **Languages**: IT/EN (configurable)
+- **Duration**: Configurable per submission type
+- **Audience Levels**: Beginner, Intermediate, Advanced
+- **Tags**: Community-driven categorization (often corrected by admins)
+
+#### Voting System
+- **Community Voting**: Public voting by eligible community members
+- **Internal Review**: Program Committee scoring and comments
+- **Ranking Algorithm**: Weighted by voter engagement (`backend/voting/models/ranking.py`)
+- **Recalculation**: Required when admins modify submission tags
+
+#### Financial Aid (Grants)
+- **Grant Types**:
+  - Ticket Only
+  - Ticket + Travel
+  - Ticket + Accommodation
+  - Ticket + Travel + Accommodation
+- **Travel Amounts** (2024 example):
+  - From Italy: €100
+  - From Europe: €250
+  - Extra Europe: €400
+- **Status Flow**: Pending → Approved → Waiting for Confirmation → Confirmed
+- **Evaluation Criteria**: Student status, community involvement, geographic diversity, employment status
+
+#### Schedule Management
+- **Rooms**: Configurable venue spaces
+- **Days**: Conference day configuration
+- **Slots**: Time-based scheduling units
+- **Schedule Items**: Can be submissions, breaks, keynotes, sponsor slots
+- **Conflicts**: System prevents scheduling conflicts
+
+### Important Business Rules
+
+1. **"Fake Deadlines"**: CFP deadlines are often extended by a week after announced closure
+2. **Keynote Allocation**: One slot reserved for Keystone sponsor, others community-selected
+3. **Voting Eligibility**: Configurable via Pretix event IDs for past attendees
+4. **Grant Budget**: Sourced from PSF, EuroPython Society, sponsors, and ticket donations
+5. **Speaker Coordination**: Avoid duplicate vouchers for speakers who also receive grants
+6. **Tag Corrections**: Admins often fix speaker-provided tags, requiring ranking recalculation
+
+### Code Search Tips
+
+- Use `grep_search` and `file_search` for searching code
+- Conference-specific code organization:
+  - `backend/conferences/` for conference models and configuration
+  - `backend/submissions/` for CFP and proposal management
+  - `backend/voting/` for community and internal voting systems
+  - `backend/grants/` for financial aid processing
+  - `backend/schedule/` for event scheduling and calendar
+  - `backend/reviews/` for Program Committee review process
+  - `backend/participants/` for attendee and speaker management
+- Frontend components are in `frontend/src/`
+- GraphQL schema is defined in `backend/schema.graphql`
+
+## Development Workflow
+
+### Writing Code
+
+Python code must be formatted by `ruff`. Verify this by running
+`ruff format $filepath1 $filepath2 ...` on all modified files. Use a file path
+relative to the repo root.
+
+Python code must be linted by `ruff`. Verify this by running
+`ruff check $filepath1 $filepath2 ...` on all modified files. Use a file path
+relative to the repo root.
+
+Python code must be type checked by `mypy`
+
+### Testing
+
+```bash
+# Run all unit tests
+docker exec -it pycon-backend-1 uv run pytest
+
+# Run specific test modules
+docker exec -it pycon-backend-1 uv run pytest backend/grants/tests/
+docker exec -it pycon-backend-1 uv run pytest backend/voting/tests/
+docker exec -it pycon-backend-1 uv run pytest backend/submissions/tests/
+```
+
+### Code Quality & Linting
+
+```bash
+# Python linting and formatting - use uv for package management
+uv run ruff format $filepath1 $filepath2 ...
+uv run ruff check $filepath1 $filepath2 ...
+uv run mypy $filepath1 $filepath2 ...
+```
+
+### Frontend Development
+
+```bash
+# Frontend development with Next.js
+cd frontend/
+pnpm dev
+
+# Build frontend
+pnpm build
+
+# Run frontend tests
+pnpm test
+```
+
+### Database Operations
+
+```bash
+# Run migrations
+docker exec -it pycon-backend-1 uv run python manage.py migrate
+
+# Create migrations for specific apps
+docker exec -it pycon-backend-1 uv run python manage.py makemigrations grants
+docker exec -it pycon-backend-1 uv run python manage.py makemigrations voting
+docker exec -it pycon-backend-1 uv run python manage.py makemigrations submissions
+
+# Check for missing migrations
+docker exec -it pycon-backend-1 uv run python manage.py makemigrations --check
+```
+
+### Conference Management Commands
+
+```bash
+# Calculate rankings (after voting period or tag changes)
+docker exec -it pycon-backend-1 uv run python manage.py calculate_rankings
+
+# Generate grant vouchers
+docker exec -it pycon-backend-1 uv run python manage.py generate_vouchers
+
+# Send notification emails
+docker exec -it pycon-backend-1 uv run python manage.py send_grant_emails
+```
+
+## Testing Framework
+
+- **Python**: pytest with Django integration
+- **Frontend**: no testing
+- **Configuration**: `pytest.ini` and `pyproject.toml` for backend
+
+### Key Testing Patterns
+
+- Use `@pytest.mark.django_db` for database tests
+- Use factories for creating test data instead of models directly
+- Frontend is not tested
+- GraphQL tests can use the schema in `backend/schema.graphql`
+- Conference-specific testing:
+  - Mock Pretix API calls for ticket validation
+  - Test ranking algorithm with various voting scenarios
+  - Test grant workflow state transitions
+  - Test schedule conflict detection
+
+### Test Data Patterns
+
+```python
+# Use factories for conference entities
+conference = ConferenceFactory()
+submission = SubmissionFactory(conference=conference)
+grant = GrantFactory(conference=conference)
+vote = VoteFactory(submission=submission)
+
+# Test ranking calculations
+ranking = RankingFactory(submission=submission)
+assert ranking.score == expected_weighted_score
+```
+
+## Frontend Architecture
+
+- **Framework**: Next.js with TypeScript
+- **Styling**: Tailwind CSS with `@python-italia/pycon-styleguide`
+- **State Management**: Apollo Client for GraphQL state
+- **Deployment**: Vercel
+- **Package Manager**: pnpm
+- **Code Generation**: GraphQL Code Generator for TypeScript types
+
+### Conference-Specific Frontend Features
+
+- **CFP Interface**: Multi-step submission form with validation
+- **Voting Interface**: Community voting with proposal browsing
+- **Review Interface**: Program Committee evaluation dashboard
+- **Schedule Display**: Conference schedule with filtering and search
+- **Grant Application**: Financial aid request form
+- **Admin Dashboards**: Conference management interfaces
+
+## External Integrations
+
+### Pretix Integration
+- **Purpose**: Ticket sales and attendee management
+- **Key Files**: `pretix.py` (in your provided files)
+- **API Usage**: Validate voting eligibility, generate vouchers
+- **Configuration**: Requires Pretix API tokens and event IDs
+
+### Email Systems
+- **Templates**: Conference-specific email templates for each phase
+- **Notifications**: Automated emails for CFP, voting, grants, schedule updates
+- **Customization**: Multi-language support (IT/EN)
+
+### Payment Processing
+- **Grant Vouchers**: Generated vouchers for approved financial aid
+- **Ticket Integration**: Coordination with Pretix for free tickets
+- **Reimbursement**: Travel and accommodation fund management
+
+## Common Workflows for AI Agents
+
+### Adding New Conference Features
+1. Update conference model in `backend/conferences/models.py`
+2. Create database migration
+3. Add admin interface configuration
+4. Update GraphQL schema and resolvers
+5. Implement frontend components
+6. Add comprehensive tests
+
+### Modifying Grant Process
+1. Update grant model and workflow states
+2. Modify evaluation criteria in review system
+3. Update email templates for notifications
+4. Test state transitions thoroughly
+5. Document business rule changes
+
+### Schedule Management
+1. Configure rooms and days in admin
+2. Use schedule builder interface for slot assignment
+3. Handle conflicts and constraints
+4. Generate speaker confirmation emails
+5. Update public schedule display
+
+Remember: The conference management domain has complex business rules and workflows that evolved over years of running PyCon Italia. Always consider the impact on the entire conference lifecycle when making changes.

backend/api/grants/mutations.py

@@ -279,6 +279,7 @@ def send_grant(self, info: Info, input: SendGrantInput) -> SendGrantResult:
             },
         )
 
+        # Grant creation is logged by signal (which detects user from instance.user_id)
         # hack because we return django models
         instance.__strawberry_definition__ = Grant.__strawberry_definition__
         return instance
@@ -299,6 +300,7 @@ def update_grant(self, info: Info, input: UpdateGrantInput) -> UpdateGrantResult
 
         for attr, value in asdict(input).items():
             setattr(instance, attr, value)
+        # Grant updates are logged by signals automatically
         instance.save()
 
         Participant.objects.update_or_create(
@@ -332,6 +334,8 @@ def send_grant_reply(
         if grant.status in (GrantModel.Status.pending, GrantModel.Status.rejected):
             return SendGrantReplyError(message="You cannot reply to this grant")
 
+        # Mark actor for history logging
+        grant._history_actor = request.user
         grant.status = input.status.to_grant_status()
         grant.save()
 

backend/api/grants/tests/test_send_grant.py

@@ -1,7 +1,7 @@
 import pytest
 
 from conferences.tests.factories import ConferenceFactory
-from grants.models import Grant
+from grants.models import Grant, GrantHistory
 from grants.tests.factories import GrantFactory
 from notifications.models import EmailTemplateIdentifier
 from notifications.tests.factories import EmailTemplateFactory
@@ -119,6 +119,15 @@ def test_send_grant(
         user=user, conference=conference, privacy_policy="grant"
     ).exists()
 
+    # Verify grant history entry is created correctly
+    assert GrantHistory.objects.filter(grant_id=grant.id).count() == 1
+
+    history_entry = GrantHistory.objects.get(grant_id=grant.id)
+    assert history_entry.event_type == GrantHistory.EventType.CREATED
+    assert history_entry.actor_type == GrantHistory.ActorType.USER
+    assert history_entry.actor == user
+    assert history_entry.message == "Grant application created"
+
     # Verify that the correct email template was used and email was sent
     emails_sent = sent_emails()
     assert emails_sent.count() == 1