Admin Guide

Managing Techs

Techs are the building blocks representing languages, frameworks, libraries, and tooling.

When to Create Techs

• Your team adopts a new language or framework
• You want to standardize on specific tooling (linters, formatters, package managers)
• Building language standards that need to reference them

Check existing techs first to avoid duplicates.

Creating a Tech

Via Web UI

1. Navigate to Techs → New Tech
2. Fill in the form:
   • Name: Lowercase identifier (e.g., ruby, fastapi, rspec)
   • Kind: Select category (language, framework, library, etc.)
   • Description: Human-readable explanation
   • Parent: Optional parent tech for hierarchies
3. Click Create Tech

Via Rails Console

# Create a new language
ruby = Tech.create!(
  name: "ruby",
  kind: :language,
  description: "Dynamic, open source programming language with a focus on simplicity"
)

# Create a framework with parent
rails = Tech.create!(
  name: "rails",
  kind: :framework,
  parent: ruby,
  description: "Web application framework written in Ruby"
)

# Create a testing framework
rspec = Tech.create!(
  name: "rspec",
  kind: :testing,
  parent: ruby,
  description: "Behavior Driven Development for Ruby"
)

# Create tooling
Tech.create!(name: "rubocop", kind: :linter, parent: ruby)
Tech.create!(name: "standardrb", kind: :formatter, parent: ruby)
Tech.create!(name: "bundler", kind: :package_manager, parent: ruby)

Tech Kinds Reference

Hierarchical Structure

Use parent relationships to model dependencies:

javascript = Tech.find_by(name: "javascript")

# React framework depends on JavaScript
react = Tech.create!(
  name: "react",
  kind: :framework,
  parent: javascript
)

# Next.js framework depends on React
nextjs = Tech.create!(
  name: "nextjs",
  kind: :framework,
  parent: react
)

# Jest testing framework depends on JavaScript
jest = Tech.create!(
  name: "jest",
  kind: :testing,
  parent: javascript
)

Editing Techs

1. Navigate to Techs
2. Click on a tech
3. Click Edit
4. Make changes
5. Save

Deleting Techs

1. Remove from all language standards first
2. Remove from all rules
3. Then delete the tech

Creating Rules

Rules encode engineering guidelines, best practices, and policies.

Rule Components

Severity Levels

Writing Effective Rules

Title: "Use bin/dev for Development Server"
Severity: error
Category: development
Text: |
  All projects must provide a `bin/dev` script...
  
  This ensures:
  - Consistent developer experience
  - No missing services
  
  Example bin/dev:
  #!/usr/bin/env bash
  exec foreman start -f Procfile.dev "$@"

Title: "Write clean code"
Severity: warning
Text: "Code should be clean and readable."

Creating Rules via Web UI

1. Navigate to Rules → New Rule
2. Fill in form: Title, Text (Markdown supported), Severity, Category, Techs
3. Choose Global (nil organization) or Organization-specific
4. Click Create Rule

Creating Rules via Rails Console

# Create a global rule
rule = Rule.create!(
  title: "All Functions Must Have Tests",
  text: <<~MD,
    Every public function must have corresponding test coverage.
    - Unit tests for business logic
    - Integration tests for API endpoints
    - Minimum 90% coverage required
  MD
  severity: :error,
  category: "testing",
  organization_id: nil  # Global
)

# Associate with techs
rule.techs << Tech.where(kind: :language)

# Organization-specific rule
org_rule = Rule.create!(
  title: "Use Company Style Guide",
  text: "All code must follow the Acme Corp style guide...",
  severity: :warning,
  category: "code_quality",
  organization: Organization.find_by(slug: "acme-corp")
)

Rule Categories

• code_quality: Maintainability, readability
• security: Auth, data protection
• performance: Optimization, caching
• testing: Coverage, mocking
• documentation: Comments, READMEs
• architecture: Design patterns
• deployment: CI/CD, infrastructure
• accessibility: WCAG compliance
• development: Workflow, tooling

Editing and Versioning

Convext uses Auditable for change tracking:

1. Edit a rule via web UI
2. Changes are automatically versioned
3. View revision history on rule page
4. Affected rulesets are notified of changes

Building Language Standards

LanguageStandards define complete tech stack templates. They answer: "When using Language X with Framework Y, what tools should we use?"

Components

Creating a Language Standard

Via Web UI

1. Navigate to Standards → New Language Standard
2. Fill in form: Identifier, Language, Framework, Tooling, Libraries, Min Version, Policy, Commands
3. Choose Global or Organization-specific
4. Click Create Language Standard

Via Rails Console

# Example: Python + FastAPI Standard
standard = LanguageStandard.create!(
  identifier: "python-fastapi-standard",
  language: Tech.find_by(name: "python"),
  framework: Tech.find_by(name: "fastapi"),
  package_manager_tech: Tech.find_by(name: "uv"),
  linter_tech: Tech.find_by(name: "ruff"),
  formatter_tech: Tech.find_by(name: "black"),
  test_framework_tech: Tech.find_by(name: "pytest"),
  min_version: "3.10",
  policy: [
    "Use type hints on all public functions",
    "Prefer async/await over synchronous code"
  ],
  commands: {
    "install" => "uv pip install -r requirements.txt",
    "test" => "pytest tests/ -v --cov",
    "lint" => "ruff check .",
    "dev" => "uvicorn main:app --reload"
  }
)

# Add libraries
standard.libraries << Tech.where(name: ["pydantic", "uvicorn", "httpx"])

Policy vs Commands

[
  "Use type hints on all public functions",
  "Prefer composition over inheritance",
  "Keep functions pure when possible"
]

{
  "install": "npm install",
  "dev": "npm run dev",
  "test": "npm test",
  "lint": "eslint ."
}

Creating RuleSets

RuleSets bundle rules and language standards for assignment to projects.

RuleSet Fields

Scope Levels

• global: Available to all organizations (marketplace)
• organization: Available within your organization only
• project: Specific to one project

Override Policies

• extend: Projects can add more rules/standards (recommended baseline)
• override: Projects can replace rules/standards (flexible guidelines)
• locked: Projects cannot modify (strict compliance, security/legal requirements)

Creating a RuleSet

Via Web UI

1. Navigate to RuleSets → New RuleSet
2. Fill in basic info: Name, Slug, Description, Scope, Override Policy, Visibility
3. Add Rules (filter by category/severity)
4. Add Language Standards
5. Click Create RuleSet

Via Rails Console

# Example: Rails 8 Best Practices RuleSet
ruleset = RuleSet.create!(
  name: "Rails 8 Best Practices",
  slug: "rails-8-bp",
  description: "Complete Rails 8 setup with modern tooling...",
  scope: "global",
  override_policy: "extend",
  visibility: "public",
  organization_id: nil
)

# Add rules
ruleset.rules << Rule.where(category: ["rails", "code_quality"])

# Add language standard
ruleset.language_standards << LanguageStandard.find_by(identifier: "ruby-rails-8-standard")

Composing Multi-Language RuleSets

fullstack_ruleset = RuleSet.create!(
  name: "Full Stack Web App",
  slug: "fullstack-web",
  scope: "organization",
  override_policy: "extend",
  visibility: "private"
)

# Add both language standards
fullstack_ruleset.language_standards << [
  LanguageStandard.find_by(identifier: "ruby-rails-8-standard"),
  LanguageStandard.find_by(identifier: "javascript-react-standard")
]

# Add rules for both stacks
fullstack_ruleset.rules << Rule.where(category: ["web", "api", "security"])

Organization Management

Creating an Organization

Organizations are created automatically via GitHub OAuth, but can also be managed manually.

User Permissions

• Admin: Full control (create/edit rules, standards, rulesets)
• Editor: Can create rules and rulesets
• Member: Can view and assign rulesets to projects
• Viewer: Read-only access

Adopting Global RuleSets

1. Browse marketplace
2. Click Adopt on a global ruleset
3. Ruleset is now available to organization projects

Enforcing Compliance

# .github/workflows/convext.yml
name: Convext Compliance Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npx @convext/cli check --strict
        env:
          CONVEXT_TOKEN: ${{ secrets.CONVEXT_TOKEN }}

Marketplace

Publishing to Marketplace

1. Create a global ruleset (organization_id: nil)
2. Set visibility to public
3. Ensure it's well-documented (clear name, description)
4. It will appear in the marketplace automatically

Marketplace Best Practices

Best Practices

Naming Conventions

• Techs: Lowercase, single word or hyphenated
  Examples: ruby, fastapi, github-actions
• Language Standards: {language}-{framework}-{variant}
  Examples: ruby-rails-8-standard, typescript-nextjs-standard
• RuleSets: Human-readable names, descriptive slugs
  Examples: "Rails 8 Best Practices" (rails-8-bp)

Gradual Rollout

1. Start as warning
2. Communicate to team
3. Gather feedback for 1-2 weeks
4. Promote to error if well-received
5. Only use critical for truly critical issues