# sanjeed5/awesome-cursor-rules-mdc architecture

> Architecture diagram of the GitHub repository sanjeed5/awesome-cursor-rules-mdc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanjeed5/awesome-cursor-rules-mdc
- Repository: https://github.com/sanjeed5/awesome-cursor-rules-mdc

## Overview

1. **What this repository is**
   - This is a Python-based content generation pipeline, not an application runtime.
   - Its job is to turn a structured library catalog in `rules.json` into many Cursor MDC rule files under `rules-mdc/`.

2. **Core data model boundary**
   - The primary input is `rules.json`, which lists libraries and tags.
   - The generator treats that file as the source of truth for what should be produced, while existing generated files in `rules-mdc/` represent the output artifact set.

3. **Main orchestration script**
   - `src/generate_mdc_files.py` is the central entry point and likely coordinates the whole workflow.
   - The README shows it supports selective processing (`--library`, `--tag`), test runs, regeneration, verbosity, worker count, and rate limiting.

4. **Configuration and runtime settings**
   - `src/config.yaml` holds operational settings such as rate limits, output directories, model selection, and processing parameters.
   - Environment variables from `.env` supply API credentials, so secret management is separated from code and config.

5. **External service dependencies**
   - Exa is used for semantic search to collect best-practice material and supporting context.
   - A large-language-model provider, typically Gemini but optionally OpenAI or Anthropic, generates the final rule content.
   - These are the only materially important external integrations in the repo’s architecture.

6. **Generation pipeline**
   - The workflow is: read the library definition → gather supporting information via Exa → feed that context plus instructions into the LLM → write an MDC file.
   - `src/mdc-instructions.txt` appears to define the generation prompt or content constraints that shape the output format.

7. **Parallelism and throughput control**
   - The generator is designed to process multiple libraries concurrently via worker settings.
   - API usage is controlled by a rate-limit mechanism, which matters because the pipeline depends on two external APIs and is sensitive to quota and throttling.

8. **Resume and failure handling**
   - `src/mdc_generation_progress.json` tracks progress across runs so interrupted jobs can resume.
   - The default mode only retries libraries that previously failed, which makes the process incremental rather than fully stateless.

9. **Intermediate artifacts**
   - `src/exa-example.py` suggests there is an example or helper path for Exa integration, likely separate from the main batch workflow.
   - `src/logs/` and the progress JSON provide observability and recovery rather than persisting application state in a database.

10. **Output layer**
   - Generated MDC files are emitted into `rules-mdc/`, with one file per library or rule topic.
   - That directory is effectively the product of the pipeline and the handoff point for downstream Cursor usage.

11. **Legacy and migration area**
   - `rules-v0-deprecated/` contains older prompt files, conversion scripts, and a conversion report.
   - Architecturally, this looks like an archive of prior-generation formats and migration tooling, distinct from the active generator path.

12. **Project tooling**
   - The project is Python-managed with `uv` (`pyproject.toml`, `uv.lock`, `.python-version`).
   - The repository also includes `.env.example` and a MIT license, indicating a lightweight CLI/tooling project rather than a deployed service.

13. **How to draw the architecture**
   - The diagram should center on a CLI batch processor in `src/generate_mdc_files.py`.
   - Show inputs from `rules.json`, `config.yaml`, and `.env`; external calls to Exa and an LLM API; internal progress/log tracking; and final writes to `rules-mdc/`.
   - Treat `rules-v0-deprecated/` as a secondary archival branch, not part of the active execution path.

Main entry points: [`src/generate_mdc_files.py`](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/generate_mdc_files.py) (Generate MDC), [`rules-v0-deprecated`](https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-v0-deprecated) (V0 archive), [`rules-v0-deprecated/convert_to_mdc.py`](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/convert_to_mdc.py) (Convert script), [`rules-mdc`](https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-mdc) (rules-mdc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_active["Active pipeline"]
  node_rules_json["rules.json<br/>source catalog<br/>[rules.json]"]
  node_generator["Generate MDC<br/>CLI orchestrator"]
  node_config["Config<br/>runtime settings<br/>[config.yaml]"]
  node_env["Secrets env<br/>api credentials<br/>[.env.example]"]
  node_instructions["Prompt rules<br/>generation prompt"]
  node_progress["Progress log<br/>resume state"]
  node_exa_example["Exa example<br/>integration example<br/>[exa-example.py]"]
  node_readme["README<br/>usage docs<br/>[README.md]"]
  node_uv_tooling["uv tooling<br/>python workspace<br/>[pyproject.toml]"]
end

subgraph group_output["Output artifacts"]
  node_rules_mdc[("rules-mdc<br/>generated corpus")]
  node_repo_rules["Cursor rules<br/>repo policy<br/>[python.mdc]"]
end

subgraph group_legacy["Deprecated archive"]
  node_deprecated_root["V0 archive<br/>deprecated migration area"]
  node_legacy_convert["Convert script<br/>migration tool<br/>[convert_to_mdc.py]"]
  node_legacy_report["Conv report<br/>migration report"]
  node_legacy_tests["Legacy checks<br/>migration validation<br/>[test_conversion.py]"]
end

node_exa(("Exa search<br/>external search API"))
node_llm(("LLM API<br/>content model"))

node_rules_json -->|"catalog input"| node_generator
node_config -->|"runtime config"| node_generator
node_env -->|"credentials"| node_generator
node_instructions -->|"prompt constraints"| node_generator
node_generator -->|"search context"| node_exa
node_generator -->|"generate content"| node_llm
node_exa -->|"context feed"| node_llm
node_generator -->|"resume state"| node_progress
node_generator -->|"write files"| node_rules_mdc
node_generator -.->|"usage guided by"| node_readme
node_uv_tooling -.->|"python env"| node_generator
node_exa_example -.->|"sample integration"| node_exa
node_deprecated_root -->|"contains"| node_legacy_convert
node_deprecated_root -->|"contains"| node_legacy_report
node_deprecated_root -->|"contains"| node_legacy_tests
node_legacy_convert -.->|"produces"| node_legacy_report
node_legacy_tests -.->|"validates"| node_legacy_convert
node_rules_mdc -.->|"coexists with"| node_repo_rules

click node_rules_json "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules.json"
click node_generator "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/generate_mdc_files.py"
click node_config "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/config.yaml"
click node_env "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/.env.example"
click node_instructions "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/mdc-instructions.txt"
click node_progress "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/mdc_generation_progress.json"
click node_exa_example "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/exa-example.py"
click node_readme "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/README.md"
click node_uv_tooling "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/pyproject.toml"
click node_rules_mdc "https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-mdc"
click node_repo_rules "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/.cursor/rules/python.mdc"
click node_deprecated_root "https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-v0-deprecated"
click node_legacy_convert "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/convert_to_mdc.py"
click node_legacy_report "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/conversion_report.json"
click node_legacy_tests "https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/test_conversion.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rules_json,node_generator,node_config,node_env,node_instructions,node_progress,node_exa_example,node_readme,node_uv_tooling toneBlue
class node_rules_mdc,node_repo_rules toneAmber
class node_deprecated_root,node_legacy_convert,node_legacy_report,node_legacy_tests toneMint
class node_exa,node_llm toneNeutral
```

## Components

### Active pipeline

Current generation flow and runtime settings

- [rules.json](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules.json): source catalog · Structured library and tag inventory used as the generation source of truth · `rules.json`
- [Generate MDC](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/generate_mdc_files.py): CLI orchestrator · Main batch entry point coordinating the generation workflow · `src/generate_mdc_files.py`
- [Config](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/config.yaml): runtime settings · Operational settings for output, models, rate limits, and processing · `src/config.yaml`
- [Secrets env](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/.env.example): api credentials · Environment-based provider credentials and other secrets · `.env.example`
- [Prompt rules](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/mdc-instructions.txt): generation prompt · Instruction text shaping the produced MDC content · `src/mdc-instructions.txt`
- [Progress log](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/mdc_generation_progress.json): resume state · Tracks completed and failed items across runs for resumption · `src/mdc_generation_progress.json`
- [Exa example](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/src/exa-example.py): integration example · Sample path for Exa integration · `src/exa-example.py`
- [README](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/README.md): usage docs · Primary usage and workflow documentation · `README.md`
- [uv tooling](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/pyproject.toml): python workspace · Project management and dependency lock files · `pyproject.toml`

### Output artifacts

Generated MDC rule files consumed by Cursor

- [rules-mdc](https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-mdc): generated corpus · Output directory containing generated Cursor MDC rule files · `rules-mdc`
- [Cursor rules](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/.cursor/rules/python.mdc): repo policy · Workspace Cursor rule file used by the repository itself · `.cursor/rules/python.mdc`

### Deprecated archive

Older prompt sets and conversion tooling

- [V0 archive](https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/main/rules-v0-deprecated): deprecated migration area · Archived earlier-generation rule sets and conversion artifacts · `rules-v0-deprecated`
- [Convert script](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/convert_to_mdc.py): migration tool · Legacy converter for older prompt files into MDC format · `rules-v0-deprecated/convert_to_mdc.py`
- [Conv report](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/conversion_report.json): migration report · Report summarizing legacy conversion outcomes · `rules-v0-deprecated/conversion_report.json`
- [Legacy checks](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-v0-deprecated/test_conversion.py): migration validation · Old validation or conversion test script · `rules-v0-deprecated/test_conversion.py`

### Other components

- **Exa search**: external search API · Semantic search source for supporting context and best practices
- **LLM API**: content model · Generates final rule text from context and instructions

## Connections

- rules.json → Generate MDC: catalog input · Source library definitions drive generation targets
- Config → Generate MDC: runtime config · Controls model, rate, and output behavior
- Secrets env → Generate MDC: credentials · Provides API keys for external services
- Prompt rules → Generate MDC: prompt constraints · Shapes content and formatting of generated MDC files
- Generate MDC → Exa search: search context · Fetches supporting material before generation
- Generate MDC → LLM API: generate content · Sends context and instructions to the model
- Exa search → LLM API: context feed · Search results inform the final prompt payload
- Generate MDC → Progress log: resume state · Reads and updates progress for incremental runs
- Generate MDC → rules-mdc: write files · Materializes generated MDC artifacts
- Generate MDC → README: usage guided by · CLI options and workflow are documented here
- uv tooling → Generate MDC: python env · Manages project dependencies and runtime setup
- Exa example → Exa search: sample integration · Demonstrates the Exa integration path
- V0 archive → Convert script: contains · Archive includes old conversion tooling
- V0 archive → Conv report: contains · Archive includes conversion report artifacts
- V0 archive → Legacy checks: contains · Archive includes validation script
- Convert script → Conv report: produces · Legacy conversion script emits summary output
- Legacy checks → Convert script: validates · Legacy checks likely exercise conversion behavior
- rules-mdc → Cursor rules: coexists with · Generated rule corpus sits alongside repository Cursor rules