Aetheron Tech Radar

A living, opinionated map of our engineering stack — inspired by the Thoughtworks Radar, tailored to Aetheron.

🚀 Quick Start for Teams

To add tech radar rules to your repository, paste this into Cursor:

Follow the instructions in the MD file you can curl from https://radar.sandbox.aetheron.com/action-setup.md

Or use this Slack command (replace YOUR_REPO_NAME):

@Cursor repo=aetheronhq/YOUR_REPO_NAME Follow the instructions in the MD file you can curl from https://radar.sandbox.aetheron.com/action-setup.md

You can also install the Radar MCP server in Cursor / Claude Code

{
  "mcpServers": {
    "aetheron-radar": {
      "command": "uv",
      "args": ["run", "https://radar.sandbox.aetheron.com/radar-mcp.py"]
    }
  }
}

Why this exists

• Internal: clear defaults, faster decisions, easier onboarding, a place to propose/track experiments, and shared "when to use X vs Y" guidance.
• External: signals we're modern and intentional, shows quality to candidates/clients, and serves as a strong tech‑marketing asset.

How it works

Each item is tagged as one of:

• Primary: our default choice.
• Consider: use when the context merits it.
• Experiment: we're currently trialing this; promising but not default.
• Avoid: known tradeoffs or misfit for our goals.

Each entry includes a short rationale and "use when" notes. The radar is collaborative and owned by everyone.

Project Structure

radar/
├── public/              # Static files served to users
│   ├── index.html       # Main radar page
│   ├── radar-entries.json # Technology data
│   ├── action-setup.md  # GitHub Action setup guide
│   └── vendor/          # Third-party libraries
├── RADAR_TO_CURSOR_RULES.md # AI prompt for generating rules
├── deploy.sh           # Deploy to S3
├── serve.sh            # Local dev server
└── .cursor/rules/radar/ # (Generated by AI using RADAR_TO_CURSOR_RULES.md)

Contributing

Please scan the radar and open PRs/issues for:

• Missing tools you rely on
• Placement changes (e.g., should be Primary vs Consider)
• Clearer "when to use" notes or better alternatives
• Experiments you're running that could become our go‑to choice

Edit public/radar-entries.json to add/update technologies.

Entry Format Example

{
  "label": "TypeScript",
  "quadrant": 1,  // 0=Infrastructure, 1=Languages & Frameworks, 2=Services & LLMs, 3=Tools & Methodologies
  "ring": 0,      // 0=Primary, 1=Consider, 2=Experiment, 3=Avoid
  "summary": "Typed superset of JS for safer, scalable apps.",
  "decision": "Default for all new frontends and Node services.",
  "when_to_use": ["Web frontends", "Node APIs", "Shared libraries"],
  "consider_alternitive": ["Python-first data services"],
  "links": [{ "title": "Docs", "url": "https://www.typescriptlang.org/" }],
  "logo": "https://cdn.jsdelivr.net/gh/simple-icons/simple-icons/icons/typescript.svg"
}

Live reference

Radar preview: https://radar.sandbox.aetheron.com/

Cursor IDE Integration

This radar can be converted into Cursor IDE rules to guide AI assistants based on our technology decisions.

Using Radar Rules in Your Repository

To automatically sync tech radar rules to your repository, add this workflow with just one line:

# .github/workflows/sync-cursor-rules.yml
name: Sync Organization Cursor Rules

on:
  pull_request:

jobs:
  sync-radar:
    uses: aetheronhq/shared-ci-workflows/.github/workflows/sync-org-cursor-rules.yml@main
    permissions:
      contents: write
      pull-requests: write

This will:

• ✅ Sync rules from https://radar.sandbox.aetheron.com to your repo
• 🤖 Automatically update on every PR
• 💬 Comment when rules are updated
• 📁 Keep radar rules organized in a /radar subfolder

How It Works

The conversion process:

• Groups technologies by quadrant and ring (Primary/Consider/Experiment/Avoid)
• Creates actionable rules for each technology
• Includes "when to use" guidance and alternatives
• Formats decisions so Cursor AI can make informed suggestions

The rules are organized in a /radar subfolder to:

• Keep them separate from project-specific rules
• Make updates and maintenance easier
• Allow clear namespace separation

Benefits

Once Cursor rules are in place, the AI will:

• 🟢 Suggest PRIMARY technologies first (e.g., PostgreSQL for databases)
• 🟡 Explain trade-offs for CONSIDER technologies
• 🔴 Warn against AVOID technologies and suggest alternatives
• 🔵 Note EXPERIMENT status for technologies in trial

For Organization Setup

See ACTION_SETUP.md for detailed instructions on:

• Setting up the GitHub Action in your repositories
• Configuration options
• Troubleshooting common issues

Getting started (local)

# Serve locally
./serve.sh
# Or: cd public && python3 -m http.server 8000

# Deploy to S3 (requires AWS credentials)
./deploy.sh

MCP tool for programmatic access

We also publish a minimal MCP server exposing one get_tech_stack_guidance tool that returns entries from the hosted JSON with optional filters. The MCP server gives you access to the radar data at the AI agent level, avoiding per-repo setup.

Client config example (Cursor/Claude-like):

{
  "mcpServers": {
    "aetheron-radar": {
      "command": "uv",
      "args": ["run", "https://radar.sandbox.aetheron.com/radar-mcp.py"]
    }
  }
}

Tool: get_tech_stack_guidance(quadrant?: int | int[], ring?: int | int[])

• Quadrants: 0 Infrastructure, 1 Languages & Frameworks, 2 Services & LLMs, 3 Tools & Methodologies
• Rings: 0 Primary, 1 Consider, 2 Experiment, 3 Avoid

Examples:

{"tool":"get_tech_stack_guidance","arguments": {"quadrant": 1, "ring": [0,1]}}

Editing Technology Entries

All technology entries are stored in public/radar-entries.json. This is the single source of truth for the radar data.

---

Maintained by Aetheron Engineering.