Cursor Rules Template: Python FastAPI Analytics for Certification Exams

Overview

The Cursor rules configuration is designed for developers building analytics tooling around certification exams. This template targets a Python FastAPI stack with PostgreSQL as the data store, SQLAlchemy as the ORM, and a secure API surface suitable for training providers delivering large-scale exams. It includes a direct, copyable .cursorrules block and stack-specific guidance to accelerate production-grade implementation with Cursor AI.

Direct answer: Use this Cursor Rules Template to generate a production-safe Cursor configuration for a FastAPI analytics backend that handles exam data, scoring, item-level analytics, and provider-level dashboards while enforcing security and testability.

When to Use These Cursor Rules

• When building certification exam analytics tools for training providers using Python FastAPI and PostgreSQL.
• When you need a repeatable, copyable Cursor configuration to enforce architecture, security, and testing standards.
• When you require clear separation of concerns across API, data access, and analytics services.
• When validation, linting, and CI/CD would benefit from a standardized Cursor block to reduce drift.
• When integrating with OAuth2/JWT secure auth and role-based access controls in production environments.

Copyable .cursorrules Configuration

# Cursor Rules Template - Python FastAPI Analytics

Framework: Python FastAPI
Stack: PostgreSQL with SQLAlchemy and Alembic
ProjectRoot: .
Language: Python

# Framework Role & Context
Role: System: You are Cursor AI, specialized for generating a copyable Cursor Rules configuration for a production-grade Python FastAPI analytics backend for certification exams. You produce precise, verifiable blocks the AI can consistently reproduce.
Context: You provide architecture, security, ORM, testing, and anti-pattern guidance tailored to training providers building exam analytics tooling.

# Code Style and Style Guides
CodeStyle: PEP8, Black, isort
Linting: Ruff or Flake8; enforce type hints where applicable
Documentation: type hints and docstrings required in public APIs

# Architecture & Directory Rules
ProjectRoot: .
RootModule: app
Modules: api, core, models, services, analytics, db, auth
StructureNotes: Keep a clean separation between API, business logic, and data access. Avoid circular imports.

# Authentication & Security Rules
Auth: OAuth2PasswordBearer with JWT (RS256)
TokenLifetime: 15m
RefreshTokenLifetime: 7d
RBAC: roles = {admin, provider, analyst, viewer}
Secrets: read from env; do not log secrets
CORS: limited to provider UI domains

# Database and ORM patterns
ORM: SQLAlchemy 2.x
Dialect: postgresql
Migrations: Alembic
Models: use declarative base; explicit relationships; avoid lazy loading in analytics queries
DataAccess: repository/service pattern; sessions per request; async support if using async libs

# Testing & Linting Workflows
Tests: pytest; pytest-asyncio where needed
CI: GitHub Actions with pytest, mypy, and linting checks
Coverage: require & report > 85%

# Prohibited Actions and Anti-patterns for the AI
Prohibitions: Do not generate raw SQL strings with string concatenation; Do not bypass authentication; Do not introduce implicit global state; Do not rely on non-production databases in migrations; Do not perform file I/O in API request handlers.

Recommended Project Structure

project-root/
├── app/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── endpoints/
│   │   │   │   ├── analytics.py
│   │   │   │   ├── auth.py
│   │   │   └── __init__.py
│   │   └── __init__.py
│   ├── core/
│   │   ├── config.py
│   │   └── logging_config.py
│   ├── models/
│   │   ├── exam.py
│   │   └── analytics.py
│   ├── services/
│   │   ├── analytics_service.py
│   │   └── exam_service.py
│   ├── auth/
│   │   ├── auth.py
│   │   └── schemas.py
│   ├── db/
│   │   ├── base.py
│   │   ├── session.py
│   │   └── schemas.py
│   └── main.py
├── alembic/
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── README.md

Core Engineering Principles

• Modularity and clear separation of concerns across API, business logic, and data access.
• Defensive coding with input validation and explicit error handling.
• Security by default: least privilege, secure storage of secrets, and proper token handling.
• Observability: structured logging, metrics, and tracing for analytics workloads.
• Reproducibility: strict migrations, deterministic builds, and pinned dependencies.
• Performance: efficient queries, bulk data processing, and pagination for analytics endpoints.
• Testability: testable services with mockable dependencies and end-to-end tests.

Code Construction Rules

• Use FastAPI with Pydantic models for request/response validation and typing.
• Use SQLAlchemy 2.x ORM with explicit sessions per request and async support when appropriate.
• Store configuration in environment variables; load via a dedicated Config module.
• Apply Alembic for database migrations; include migration checks in CI.
• Implement OAuth2 with JWT (RS256) and role-based access control for providers and admins.
• Avoid N+1 query patterns; cache and batch analytics computations where possible.
• Do not embed secrets in code or commit them to VCS.
• Write unit tests for data access and services; include integration tests for API endpoints.

Security and Production Rules

• Enforce TLS in production; disable debug endpoints in production builds.
• Use token expiry and refresh tokens; rotate signing keys and monitor for anomalies.
• Validate all inputs; prevent SQL injection, XSS, and CSRF in API routes where applicable.
• Limit payload sizes; implement rate limiting on analytics endpoints.
• Isolate analytics processing jobs; use background tasks for long-running data crunching.

Testing Checklist

• Unit tests for models and services with deterministic fixtures.
• Integration tests for API endpoints with a test database; run migrations before tests.
• End-to-end tests for analytics dashboards and data pipelines.
• Linting and type checks in CI; ensure 100% type coverage where feasible.
• Security tests for auth flows and token validation.

Common Mistakes to Avoid

• Skipping migrations or directly modifying the production database schema.
• Over-optimizing without measuring; add proper indices for analytics queries.
• Ignoring input validation leading to injection or invalid data states.
• Using global mutable state or non-deterministic tests that cause flakiness.
• Neglecting secrets management and secret rotation practices.

Related implementation resources: AI Agent Use Case for Call Centers Using Conversation Transcripts to Monitor Service Quality and Why AI-assisted product development needs repeatable, production-grade systems.

FAQ

What is a Cursor Rules Template?

A Cursor Rules Template provides a copyable, stack-specific configuration block that guides AI-assisted development. This template focuses on a Python FastAPI analytics backend for certification exam data, defining architecture, security, ORM usage, testing, and anti-patterns to prevent drift in production.

Which stack does this template target?

It targets a Python FastAPI stack with PostgreSQL as the data store, SQLAlchemy as the ORM, Alembic for migrations, and OAuth2/JWT security, optimized for analytics around certification exams and training providers.

How do I integrate the .cursorrules block?

Copy the entire .cursorrules block from the Copyable section and paste it into your project root as .cursorrules. The Cursor AI will use it to configure roles, architecture, and anti-patterns for your FastAPI analytics backend.

What security considerations are mandatory?

Use RS256-signed JWTs, enforce RBAC, keep secrets in environment variables, rotate keys, apply TLS, implement CSRF protections for state-changing operations, and restrict CORS to provider domains.

What tests should I include?

Unit tests for services and models, integration tests for API endpoints with a test database, and end-to-end checks for analytics data flows. Include CI steps for linting, type checks, and migrations validation.

How do I avoid common performance pitfalls?

Avoid N+1 queries by using proper joins and eager loading where appropriate, paginate large analytics results, and cache expensive aggregations. Profile queries and add appropriate indexes on analytics tables.