Back to Documentation

Core Concepts

Understand the data models that power Convext.

This guide explains the fundamental data models in Convext and how they relate to each other. Understanding these concepts is essential for effectively using and administering Convext.

Core Entities

Techs

Building blocks (languages, frameworks)

Rules

Engineering guidelines & policies

Language Standards

Tech stack recipes & tooling

RuleSets

Bundles assigned to projects

Techs

Techs represent technologies used in software development: languages, frameworks, libraries, tooling, databases, and CI/CD systems.

Tech Kinds

Kind Description Examples
language Programming languages ruby, python, javascript
framework Web/app frameworks rails, fastapi, react
library Reusable libraries devise, pydantic, lodash
testing Test frameworks rspec, pytest, jest
linter Code quality linters rubocop, eslint, ruff
formatter Code formatters standardrb, prettier
package_manager Dependency managers bundler, npm, pip
database Database systems postgresql, redis
ci_cd CI/CD platforms github-actions, circleci

Hierarchical Structure

Techs can have parent-child relationships to model dependencies:

  • jest (testing) belongs to javascript (language)
  • nextjs (framework) depends on react (framework) and typescript (language)
  • rspec (testing) belongs to ruby (language)

Rules

Rules are engineering guidelines, best practices, and policies that codify how your team builds software.

Severity Levels

critical

Security vulnerabilities, data loss risks.

"Never commit secrets to git"

error

Bugs, broken builds, compliance violations.

"All public functions must have tests"

warning

Code smells, style violations.

"Prefer const over let"

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

Language Standards

LanguageStandards are tech stack templates that define the complete tooling setup for a language or framework combination.

Purpose

LanguageStandards answer: "When using Language X with Framework Y, what tools should I use?"

Example: Python + FastAPI Standard

  • Language: python
  • Framework: fastapi
  • Package Manager: uv
  • Linter: ruff
  • Formatter: black
  • Test Framework: pytest
  • Libraries: pydantic, uvicorn, httpx

Policy and Commands

Policy (Array)

High-level guidelines

  • • Use type hints on all public functions
  • • Prefer async/await over callbacks
  • • Keep dependencies minimal

Commands (Hash)

Standard scripts

test: "pytest tests/"
lint: "ruff check ."
dev: "uvicorn main:app --reload"

RuleSets

RuleSets are bundles of Rules and LanguageStandards that get assigned to projects.

Scopes

  • global: Available to all organizations (marketplace)
  • organization: Organization-specific
  • project: Single 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)

Applying to Projects

Projects can have multiple rulesets assigned. When syncing, the CLI merges all rules and standards.

# Example: Multi-language project
project.rule_sets = [
  RuleSet.find_by(slug: "rails-8-bp"),
  RuleSet.find_by(slug: "nextjs-ts-standard"),
  RuleSet.find_by(slug: "security-essentials")
]

Relationships

Tech → LanguageStandard

A Tech can be referenced by many LanguageStandards in different roles (language, framework, linter, formatter, test framework, package manager, or library).

Rule ↔ Tech

Rules can be tagged with multiple Techs. When syncing, rules are filtered by the project's tech stack.

RuleSet ↔ Project

A Project can have multiple RuleSets assigned. When syncing, all rules and standards are merged.

Scoping and Visibility

Scope Hierarchy

Global (organization_id: nil)
  ↓ available to
Organization (organization_id: X)
  ↓ applied to
Project (belongs to organization)

Access Control

  • Tech: All techs are global
  • Rule: Can be global or organization-specific
  • LanguageStandard: Can be global or organization-specific
  • RuleSet: Can be global or organization-specific

Best Practices

✅ Do

  • • Write clear, actionable rule titles
  • • Choose appropriate severity levels
  • • Tag rules with relevant techs
  • • Keep standards focused on one tech stack
  • • Use descriptive ruleset names

❌ Don't

  • • Create duplicate techs or rules
  • • Write vague rules ("write good code")
  • • Lock everything (use sparingly)
  • • Over-prescribe minor style preferences
  • • Create overlapping rulesets

Quick Example

Here's how the entities work together for a Rails 8 project:

# 1. Techs already exist
ruby = Tech.find_by(name: "ruby")
rails = Tech.find_by(name: "rails")
rspec = Tech.find_by(name: "rspec")

# 2. Create a language standard
standard = LanguageStandard.create!(
  identifier: "ruby-rails-8",
  language: ruby,
  framework: rails,
  test_framework_tech: rspec,
  # ... other tooling
)

# 3. Create rules
rule = Rule.create!(
  title: "Use bin/dev for Development",
  severity: :error,
  category: "development"
)

# 4. Create a ruleset
ruleset = RuleSet.create!(
  name: "Rails 8 Best Practices",
  slug: "rails-8-bp",
  scope: "global"
)
ruleset.rules << rule
ruleset.language_standards << standard

# 5. Assign to project
project.rule_sets << ruleset

When the developer runs convext sync, all rules and standards from the assigned rulesets are merged and configuration files are generated.

CLI Guide IDE Integration