Contributing

⚠️ Only `src/content/docs/` is published

This repo carries two copies of every page — a top-level tree (services/, deployment/, architecture/, …) left over from Mintlify, and src/content/docs/…. Astro Starlight’s docsLoader() reads only src/content/docs/ (src/content.config.ts), so the top-level tree is dead text.

It is also the copy people keep editing. Verified 2026-08-27: services/backend.mdx was last touched 2026-08-24 and src/content/docs/services/backend.mdx on 2026-08-11, and content added in that gap does not appear on dev-devdocs.logrite.ai at all. Two weeks of documentation was written where nobody could read it.

Until the duplicate tree is removed, edit both copies, and check the live page before believing a doc landed:

curl -s https://dev-devdocs.logrite.ai/services/backend/ | grep -c '<a phrase you just added>'

Branch Strategy

Logrite uses a single-branch strategy: every service repo has main and nothing else.

Branch	Purpose	Deploys to	Auto-deploy
`main`	The only branch	The dev host, `dev-*.logrite.ai`	Yes — the deploy watcher polls the tip every 60s

A push to main deploys to dev, never to prod. Prod runs the same branch but moves only when a human promotes a tested image from dev through the management console. There is deliberately no branch, and no push, that reaches production.

The two hosts are separate VMs running one instance of each service, so there is no main+dev pair of ports on one box; the +1 ports that used to distinguish them are gone.

Workflow

Standard Feature Development

# 1. Start on main
git checkout main
git pull origin main

# 2. Create a feature branch LOCALLY — do not push it
git checkout -b feature/agent-builder-ui

# 3. Develop and commit
git add src/components/Agents/
git commit -m "feat: add AgentBuilder NLP creation UI"

# 4. Open a PR against main
#    Push the branch only for the life of the review, then delete it.
git push origin feature/agent-builder-ui
gh pr create --base main --title "Add AgentBuilder UI"

# 5. After review: merge to main, delete the branch
git push origin --delete feature/agent-builder-ui

# 6. The deploy watcher sees the new tip within 60s and deploys it to DEV.
#    Watch the job at https://management.logrite.ai

# 7. Test on dev (dev-*.logrite.ai)

# 8. To ship it to production, PROMOTE the tested image from the management
#    console. Promotion copies the exact image that was tested on dev; it does
#    not rebuild, and it is the only path to prod.

Hotfix to Production

# 1. Branch from main
git checkout main
git pull
git checkout -b hotfix/fix-payment-query-timeout

# 2. Fix and commit
git commit -m "fix: increase payment query timeout to 30s"

# 3. PR directly to main
gh pr create --base main --title "Hotfix: payment query timeout"

# 4. After merge the fix deploys to DEV automatically. Verify it there, then
#    promote from the management console to put it in production.
#    There is no second branch to keep in sync.

Commit Message Convention

<type>: <short description>

Types:
  feat:     New feature
  fix:      Bug fix
  refactor: Code refactoring (no behavior change)
  docs:     Documentation changes
  test:     Adding or modifying tests
  chore:    Dependency updates, build changes
  perf:     Performance improvements

Examples:

feat: add NLP agent creation via /api/v1/agent-builder/parse
fix: semantic search returns 500 when model is unloading
docs: update port map with agent-runner port 9400
test: add chat-scenarios tests for anomaly queries

Pull Request Guidelines

All PRs require at least one review
PRs to main require a working dev deployment
Include test evidence (health check output, screenshot, or test run)
Update this playbook if adding a new service or changing ports/endpoints

Code Style

TypeScript / JavaScript

ESLint + Prettier configured per repo
Run npm run lint before committing

Python (MCP Server)

Black formatter
Run black . before committing

Java (Backend)

Google Java Format
Enforced by Maven checkstyle plugin

File size — 300 lines, enforced

Three repos fail the build on a source file over 300 lines. This is not a style preference you can talk your way past in review; it is a gate, and it runs before anything slow.

Repo	Command	What is limited
`Logrite-UI`	`npm run lint:filesize`	every `.js/.jsx/.ts/.tsx` under `src/`
`logrite-analyzer`	`npm run filesize:check`	every `.ts` under `src/` except generated output and prompt text
`Logrite-AI`	`mvn checkstyle:check`	files and methods: `FileLength` 300, `MethodLength` 80, `CyclomaticComplexity` 15, `ParameterNumber` 8 — across `src/main/java` and `src/test/java`

All three suppression lists are currently empty, and each repo carries a second script whose only job is to fail when the list grows:

npm run lint:filesize                  # Logrite-UI
./scripts/filesize-ratchet.sh          # logrite-analyzer
./scripts/checkstyle-ratchet.sh        # Logrite-AI (run from logwrite-api/)

Adding an entry to a suppression list to make a build pass will fail the build. Split the file, or the method. If you genuinely believe a file is the exception, that is a conversation to have on the PR before you write the entry — the last three times someone argued a file was “the floor”, it turned out to be splittable without touching behaviour.

Do not delete a ratchet script because its list is empty. An empty list is the state the gate exists to reach; the script is also the check that fails a new oversized file, so removing it removes the limit and nothing goes red.

Related, in logrite-analyzer only: npm run lint:perf holds three performance rules the same way. regexp-in-body is a hard zero (it was a measured 37% of scan CPU); the other two are ratchets whose recorded count may only go down. npm run lint:perf:record refuses to write a higher count, so a red run means fixing the code, not the baseline.

logrite-ai-service came under the same limit on 22 August 2026, with 58 files grandfathered and the list shrink-only:

Command	What is limited
`npm run lint:filesize`	every `.ts` under `src/` and `tests/`, except generated output
`npm run lint:cycles`	new runtime `require` cycles, measured on the compiled `dist/`
`npm run lint:literals`	the compiled output must hold the same strings and property names
`npm run snapshot:contract`	tool registry, system prompt, route table, Warden’s ordered patterns
`npm run verify`	all of the above, plus the full suite

Two of those are specific to that service and worth knowing about. lint:literals exists because in Cortex the text is the behaviour — a reworded prompt or a renamed tool inside a large file-move compiles, passes every test, and is invisible in review; a pure re-home cannot change which strings the output contains, so the gate sees it. snapshot:contract covers what that cannot: that the strings are still wired to the same tools, routes and rules, in the same order.

Its structural gates also run inside Dockerfile.ci, not only in the workflow — see the note on CI below.

The remaining three services have no size gate. logrite-semantic-api, logrite-mcp-server and logrite-webhook hold seven files over the limit between them. There, the 300-line rule is a convention rather than a build failure, so do not assume a green build means your new file is under it.

A green tick means something again — but only about what actually ran. From 19 August 2026 until the September migration every GitHub Actions run in the organisation failed in seconds on a billing block, with no step executed, so neither colour was a verdict. checks now runs on the self-hosted logrite-dev runners on the dev VM, so a red ✗ is a real failure and a green tick means those gates passed — not that a gate the service does not have would have. Run the commands above locally before you open a PR. A job sitting in Queued is a stopped runner service (systemctl status 'actions.runner.*' on deployd-dev), not a billing problem.

Testing Before PR

# Node.js services: run tests
npm test

# AI Service: hermetic, no running service needed
cd services/ai-service/dev/logrite-ai-service
npm test

# After a deploy, every service's state and health (dev VM)
curl -s 'http://127.0.0.1:8090/api/services?host=dev' | python3 -m json.tool