Cursor Project Rules — GSoC Organizations Guide

# Cursor Project Rules — GSoC Organizations Guide

You are working in a production-grade, SEO-critical, read-heavy Next.js App Router project.
Architectural consistency, caching correctness, and design uniformity are NON-NEGOTIABLE.

────────────────────────────────────────
GENERAL PRINCIPLES
────────────────────────────────────────
- This is a public, SEO-indexable application.
- Prefer Server Components by default.
- Introduce Client Components ONLY when strictly required (interactivity).
- Do NOT introduce new patterns if an existing one solves the problem.
- Optimize for long-term maintainability over short-term speed.

When in doubt: reuse > extend > create new.

────────────────────────────────────────
ROUTING & FRAMEWORK RULES
────────────────────────────────────────
- Use Next.js App Router only.
- Follow existing folder conventions in `/app`.
- Use `generateStaticParams` and `generateMetadata` consistently with existing pages.
- Do NOT introduce Pages Router patterns or legacy APIs.

────────────────────────────────────────
CACHING & DATA FETCHING (CRITICAL)
────────────────────────────────────────
- Prefer Static Generation or ISR wherever possible.
- NEVER use `cache: "no-store"` on SEO pages.
- Wrap ALL Prisma read queries with `unstable_cache`.
- Historical GSoC data is immutable → cache aggressively (1 year+).
- Current year data changes yearly → long ISR (30 days+).
- Use tag-based invalidation (`revalidateTag("year-YYYY")`) for updates.
- Avoid per-request DB calls without caching.

DO NOT:
- Fetch uncached data inside `generateMetadata`.
- Use cookies, headers, or auth-based cache keys.
- Use `force-dynamic` unless absolutely unavoidable.

────────────────────────────────────────
DATABASE & API RULES
────────────────────────────────────────
- Prisma + MongoDB is the ONLY data access layer.
- No raw MongoDB queries.
- No business logic inside API routes.
- APIs return DATA ONLY (never HTML).
- Use cached selectors/shared data functions instead of recomputing.

────────────────────────────────────────
COMPONENT REUSE (VERY IMPORTANT)
────────────────────────────────────────
Before creating ANY new component:
1. Search for an existing component.
2. Check if it can be reused as-is.
3. Check if it can be extended via props/variants.
4. ONLY create a new component if reuse is impossible.

❌ BAD:
- Creating a new card, button, or search UI that already exists.

✅ GOOD:
- Reusing and extending existing components.

Examples:
- Organization listings MUST reuse the existing `OrganizationCard`.
- Action buttons MUST reuse the shared `Button` component.
- Search and filters MUST reuse the existing `SearchBar` / filter components.
- Pagination MUST reuse the shared pagination component.

If building a new feature that uses:
- Organization cards → reuse the existing card
- Buttons → reuse existing Button variants
- Search input → reuse existing SearchBar
- Badges/tags → reuse existing Badge components

If extension is needed:
- Add props or variants
- Do NOT fork or duplicate components

────────────────────────────────────────
DESIGN SYSTEM & UI CONSISTENCY
────────────────────────────────────────
- Follow existing project design patterns strictly.
- Use existing spacing, typography, and layout conventions.
- Do NOT introduce arbitrary margins, paddings, or font sizes.
- Reuse existing layout wrappers and section structures.

COLORS & THEMING:
- Use ONLY existing color tokens and design variables.
- Do NOT hardcode colors.
- Do NOT introduce new colors without explicit instruction.
- Respect dark/light mode rules if present.

Consistency > novelty.

────────────────────────────────────────
GRAPHS & DATA VISUALIZATION
────────────────────────────────────────
Graphs are data-heavy and MUST follow strict rules:

- Reuse existing graph/chart components if present.
- Use a single charting approach/library consistently.
- Do NOT mix multiple visualization libraries.
- All graph data MUST be precomputed and cached.
- Graphs MUST be server-rendered where possible.
- Avoid client-only graph rendering unless required by the library.

Graph rules:
- No real-time graphs (data is yearly).
- No per-request aggregation queries.
- Use cached aggregated data (unstable_cache or KV if approved).
- Axes, colors, and legends must follow existing styles.

If a new graph type is required:
- Check for an existing similar graph.
- Extend the existing abstraction.
- Do NOT create one-off chart components.

────────────────────────────────────────
SEO RULES (NON-NEGOTIABLE)
────────────────────────────────────────
- All indexable pages MUST be server-rendered.
- Avoid client-side data fetching for SEO pages.
- `generateMetadata` must use cached data only.
- Ensure canonical URLs and consistent metadata patterns.
- Query-param pages must remain crawlable and stable.

────────────────────────────────────────
PERFORMANCE & SCALE
────────────────────────────────────────
- Assume seasonal traffic spikes (GSoC announcements).
- Minimize serverless invocations.
- Avoid unnecessary recomputation.
- Prefer long-lived caches over frequent regeneration.

────────────────────────────────────────
AI CHANGE LOGGING (WHEN NECESSARY)
────────────────────────────────────────
If YOU (the AI) generate or significantly modify code, log it ONLY for important changes.

WHEN TO LOG (create file in `/md-docs/`):
- Major architectural changes (e.g., caching system)
- New API implementations or breaking API changes
- Database schema changes
- New integrations or third-party services
- Security-related changes
- Changes that future contributors MUST understand

WHEN NOT TO LOG:
- Bug fixes
- Minor UI tweaks
- Refactoring without behavior change
- Documentation updates
- Config changes
- Routine maintenance

Rules:
- Only document changes that would surprise or confuse future contributors.
- Create a file inside `/md-docs/` (NOT `/ai-mds/`).

Naming convention:
- `1-feature-name.md`
- `2-bugfix-name.md`
- `3-refactor-name.md`
(increment numbers sequentially)

File structure (STRICT):
1. High-level summary (what & why)
2. Files created/modified
3. Architectural decisions made
4. Caching implications
5. Anything that might surprise a human reviewer

Example structure:

# Feature: Organization Stats Page

## Summary
Brief description of what was added/changed and why.

## Files Modified / Created
- app/organizations/stats/page.tsx
- lib/stats.ts

## Design & Architecture Notes
- Reused existing OrganizationCard
- Used cached Prisma selectors
- Followed existing layout patterns

## Caching Details
- ISR: 30 days
- unstable_cache used for stats aggregation
- Tagged with `year-2025`

## Notes for Reviewers
- No new colors introduced
- No new UI patterns added

DO NOT skip this step.

────────────────────────────────────────
GIT & COMMIT DISCIPLINE (MANDATORY)
────────────────────────────────────────
All changes must follow strict commit hygiene.
Commits should be easy to review, cherry-pick, and revert.

COMMIT MESSAGE FORMAT (REQUIRED):
<type>: <short one-line summary>

Allowed types:
- feat: new feature
- fix: bug fix
- refactor: code restructure without behavior change
- chore: tooling, config, cleanup
- docs: documentation changes
- perf: performance improvements
- test: adding or updating tests

COMMIT MESSAGE RULES:
- ONE LINE only (no paragraphs).
- Be concise and descriptive.
- No trailing periods.
- No emojis.
- No vague messages.

GOOD examples:
- feat: add cached organization stats api
- feat: reuse organization card in tech stack page
- feat: add year-based cache tags
- perf: cache prisma org selectors
- refactor: extract reusable search filter component
- chore: align api cache-control headers
- docs: document yearly cache invalidation process

BAD examples:
- update code
- fix stuff
- refactor organization page
- caching improvements
- final changes

FEATURE SIZING RULES:
- Large features MUST be split into smaller commits.
- Each commit should represent ONE logical change.
- Avoid mixing unrelated changes in one commit.

Example (GOOD):
- feat: add org stats selector
- perf: cache org stats selector
- feat: render org stats graph
- docs: log ai changes for org stats

Example (BAD):
- feat: add org stats feature

COMPOSITE FEATURES:
When a feature has multiple small parts, prefer:
feat: feature A + feature B + feature C

Example:
- feat: org filters + pagination + url sync

COMMENTING RULES (VERY IMPORTANT):
- Do NOT add comments that restate the obvious.
- Do NOT comment WHAT the code does if the code is clear.
- ONLY add comments when:
  - Explaining a non-obvious decision
  - Documenting a workaround or edge case
  - Warning future maintainers about constraints
  - Explaining caching or architectural reasoning

BAD comment:
- // fetch organizations from database

GOOD comment:
- // Cached at year-level to avoid DB hits during GSoC traffic spikes

AI RESPONSIBILITY:
- AI-generated commits must follow the same standards.
- If AI introduces a feature or refactor:
  - Split commits properly
  - Log changes in `/ai-mds/`
  - Ensure commit messages align with the changes

Failure to follow commit rules is considered a review-blocking issue.

────────────────────────────────────────
FILE ORGANIZATION
────────────────────────────────────────

IMPORTANT ROOT-LEVEL FILES (DO NOT MOVE):
- README.md              → Project overview
- CONTRIBUTING.md        → Contribution guidelines
- SECURITY.md            → Security policy
- architecture.md        → System architecture
- .cursorrules           → This file (AI coding rules)

DOCUMENTATION FOLDERS:
- /docs/                 → Technical documentation (caching, admin, testing)
- /md-docs/              → Supplementary docs (API docs, deployment guides, AI changelogs)

FILE NAMING CONVENTIONS:
- Use lowercase with hyphens: `my-feature.md`
- Serialized files in md-docs: `1-name.md`, `2-name.md`, etc.

────────────────────────────────────────
ABSOLUTE DO-NOTs
────────────────────────────────────────
- Do NOT introduce Redis/KV unless explicitly requested.
- Do NOT duplicate components.
- Do NOT break existing caching guarantees.
- Do NOT introduce new design systems.
- Do NOT ignore this file.
- Do NOT move root-level .md files listed above.

If unsure about a decision:
STOP and ASK before proceeding.