Cursor Rules Template: Recycling Workload Forecasting Dashboard

Overview

Direct answer: This Cursor Rules Template provides a copyable .cursorrules configuration tailored for a Python FastAPI + PostgreSQL stack to build recycling workload forecasting dashboards. Paste the block into your project root and let Cursor AI guide data ingestion, modeling, and dashboard generation with strict architecture rules.

The template targets a Python FastAPI + SQLAlchemy 2.0 + PostgreSQL data layer, with Pandas for data processing and Plotly for dashboards. It codifies roles, security, ORM patterns, testing, and anti-patterns so Cursor AI remains aligned with safe, reproducible AI-assisted development.

When to Use These Cursor Rules

• Building forecasting dashboards for recycling and waste management operations.
• Enforcing a repeatable, auditable data pipeline from ingestion to visualization.
• Starting a new analytics project where Cursor AI must follow defined security and architecture constraints.
• Integrating time-series forecasting with interactive Plotly dashboards in a FastAPI backend.
• Onboarding new developers with a copyable, stack-specific ruleset for faster ramp-up.

Copyable .cursorrules Configuration

Framework: Python FastAPI + SQLAlchemy 2.0 + PostgreSQL
Context: Recycling workload forecasting dashboards powered by Cursor AI
Framework Role & Context
- You are a Cursor AI assistant configured for a Python FastAPI + PostgreSQL stack.
- Goal: produce reliable, testable code and a safe data pipeline for forecasting dashboards.

Code Style and Style Guides
- Follow PEP8, type hints, and docstrings; use Black and isort
- Maintain consistent naming conventions and module boundaries

Architecture & Directory Rules
- Project layout: app/ with submodules api, core, db, models, schemas, services, tests
- Async DB access via SQLAlchemy 2.0 AsyncSession
- Use Alembic for migrations

Authentication & Security Rules
- OAuth2 Password Bearer with JWT tokens
- Keep credentials in environment variables; secret management
- Enforce least privilege for API endpoints

Database and ORM patterns
- PostgreSQL, SQLAlchemy 2.0 (Async), declarative models
- Use pydantic for request/response validation
- Avoid loading entire tables; paginate and stream large results

Testing & Linting Workflows
- Pytest with pytest-asyncio for async code
- Pre-commit hooks: black, ruff, isort
- CI: run unit/integration tests on PRs

Prohibited Actions and Anti-patterns for the AI
- Do not bypass authentication checks
- Do not hardcode credentials or secrets
- Do not generate UI scaffolds that bypass validation
- Do not drift from the project’s directory structure

Cursor AI Instructions
- Provide concrete, copyable code blocks and file templates when applicable
- Ensure data models reflect recycling forecasting domain: WorkloadForecast, IngestionMetrics, ForecastResult
- Output must stay within the Python FastAPI + PostgreSQL ecosystem

Example Endpoints (illustrative)
- app/api/v1/forecast.py: GET /forecasts, POST /forecasts
- Data path: /data/recycling/forecasts.parquet
- Endpoints return validated Pydantic schemas and chart-ready data

Recommended Project Structure

project-root/
├── app/
│   ├── main.py
│   ├── api/
│   │   └── v1/
│   │       ├── endpoints/
│   │       │   └── forecast.py
│   │       └── deps.py
│   ├── core/
│   │   ├── config.py
│   │   ├── security.py
│   │   └── logging.py
│   ├── db/
│   │   ├── base.py
│   │   ├── session.py
│   │   └── models.py
│   ├── models/
│   │   └── forecast_models.py
│   ├── schemas/
│   │   └── forecast_schemas.py
│   ├── services/
│   │   └── forecast_service.py
│   └── tests/
│       └── test_forecast.py
├── alembic/
├── data/
│   └── recycling/
│       └── forecasts.parquet
├── Dockerfile
└── requirements.txt

Core Engineering Principles

• Single source of truth: one canonical data model for forecasts and inputs.
• Explicit boundaries between API, data layer, and visualization.
• Idempotent builds and migrations; reproducible environments.
• Security by default: encrypted secrets, scoped tokens, and minimal access.
• Observability: structured logs, metrics, and tracing for dashboards.
• Cursor AI rules enforce safe, auditable AI-assisted development patterns.

Code Construction Rules

• Use FastAPI endpoints with Pydantic models for input validation and output schemas.
• ORM models must be defined in app/db/models.py; use AsyncSession for DB access.
• Data ingestion should read from parquet or CSV in /data and cache results in PostgreSQL.
• Forecast computations should leverage Pandas, avoid in-memory joins on large datasets.
• Visualizations should be returned as JSON-ready structures for Plotly charts in the frontend.
• Test coverage: unit tests for data processing, integration tests for API endpoints.
• Do not bypass authentication or return raw DB cursors to clients.

Security and Production Rules

• Store DB credentials and API keys in environment variables; do not commit them.
• Use OAuth2 with JWT tokens and refresh tokens; enforce token scopes for endpoints.
• Validate all inputs; apply strict CORS rules and rate limiting where necessary.
• Enable HTTPS, rotate secrets, and use secure cookie flags for JWT storage.
• Run migrations in CI with a pin to a known Alembic revision; never auto-migrate in production.

Testing Checklist

• Unit tests for data processing functions (Parquet read, rolling means).
• Integration tests for API endpoints with a test PostgreSQL database.
• End-to-end tests that simulate a dashboard data fetch and chart payload.
• Linting and type checks in CI; verify code style with Black and Ruff.
• Security tests for JWT expiry and token revocation scenarios.

Common Mistakes to Avoid

• Hardcoding database credentials or secret values in source files.
• Loading entire tables into memory for forecasting; prefer streaming/pagination.
• Neglecting input validation on forecast parameters or data schema changes.
• Combining UI logic with business rules in API endpoints; separate concerns.
• Skipping migrations or bypassing Alembic in deployment pipelines.

Related Cursor rules templates

Explore adjacent Cursor rules templates for similar stacks, workflows, and production constraints.

• Cursor Rules Template: IoT Water Monitoring with FastAPI & PostgreSQL
• Cursor Rules Template: Personal AI OS with Notes, Tasks, Calendar, Memory and Chat (FastAPI + PostgreSQL)
• Cursor Rules Template: SaaS Metrics Dashboard with Stripe Integration
• Cursor Rules Template: Sales Pipeline SaaS with Lead Scoring, Email Tracking, and AI Dashboards

FAQ

What is the purpose of this Cursor Rules Template?

The template provides a ready-to-paste .cursorrules block for building recycling workload forecasting dashboards with a Python FastAPI + PostgreSQL stack, enforcing architecture, security, and testing guidelines for Cursor AI-driven development.

Which stack does this template target?

It targets Python FastAPI for the API layer, SQLAlchemy 2.0 for ORM, PostgreSQL as the database, Pandas for data processing, and Plotly for dashboards, all governed by Cursor AI rules.

How do I use the copyable .cursorrules block?

Copy the block from the Copyable Configuration section and paste it into a new .cursorrules file at your project root. Cursor AI will read the rules to constrain actions, enforce structure, and guide development.

Can I customize data sources or models?

Yes. The rules specify the modular data layer and forecasting domain models; you can adapt source paths, schemas, and ORM mappings while preserving architecture rules and security patterns.

How do I run tests and ensure production readiness?

Run unit tests for data processing, integration tests for API endpoints, and end-to-end checks for dashboard data flows. Use CI to enforce linting, type checks, and migrations before deploying.