Foundations

Engineering Standards

Unified engineering standards for all echology projects. Python, TypeScript, security, API design, AI patterns, deployment.

Engineering Philosophy

Code Quality

Write code at or above industry standard. Clean, readable, unsurprising. Prefer well-known patterns over clever solutions. If a junior engineer can't follow the logic, simplify it. Code is read far more than it is written. Optimize for the reader.

Every module should do one thing well. Functions should be short enough to hold in your head. Names should be precise: a function called validate should validate, not validate-and-transform-and-persist.

Foundation connection: Truth over plausibility. Code that looks sophisticated but is hard to reason about introduces the same risk as a model that sounds confident but is wrong.

Security

Security is not a feature. It is a constraint on every feature.

Never commit secrets, credentials, API keys, or tokens. Use environment variables.
Validate at system boundaries: user input, external APIs, webhook payloads.
Default to least privilege. Bind to localhost. Require authentication for anything network-exposed.
No command injection, SQL injection, XSS, or path traversal. Parameterized queries, template escaping, safe path construction by default.
Audit dependencies. Fewer dependencies means fewer attack surfaces.
When in doubt, fail closed. A system that refuses to act is safer than one that acts on bad input.

Foundation connection: Integrity under pressure. A system that can be compromised has no integrity.

Forward Thinking

Design decisions should compound, not create debt. Before writing code, ask: does this make the next decision easier or harder?

Build interfaces that can be extended without modifying existing code.
Prefer composition over inheritance. Small, combinable pieces scale better than deep hierarchies.
Write tests for behavior, not implementation. Tests that break when you refactor are noise.
Keep the dependency graph directional. Nothing flows backward.
When a pattern appears three times, it may warrant abstraction. Before three, it is premature.

Foundation connection: Structure over volume. A well-structured codebase reveals its own architecture.

Graceful Degradation

Every optional capability must work when absent. The system runs without Ollama, without Qdrant, without the engine. Each layer adds capability but is never required by the layer below it.

This is an architectural commitment, not a convenience. A system that breaks when an optional service is unavailable has made that service mandatory. Test the degraded path, not just the happy path.

Foundation connection: Integrity under pressure. The system must function correctly under adverse conditions, not just ideal ones.

Python

Version: Python 3.11+
Environment: uv for environment management and package installation
Config: Every project gets a pyproject.toml and a .venv/ directory
Build backend: setuptools.build_meta
Dependencies: Pin with minimum versions and upper bounds. Minimize dependencies. Prefer the standard library.
Formatter/linter: ruff. Line length 120. Double quotes. Import sorting via isort.
Testing: pytest. Tests in tests/ at the project root. Run before committing changes to any core module.

TypeScript

Package manager: pnpm
Strict mode: TypeScript strict mode enabled
Formatting: Prettier
Linting: ESLint

Git

Branching: main is the default branch. Feature work on branches, merged via PR. Keep commits atomic: one logical change per commit.
Commit messages: Short imperative subject line. Body for context when the change is non-obvious.
Never commit: .env, credentials, API keys, secrets, .venv/, node_modules/, __pycache__/, .DS_Store

Project Structure

Python API/Service

project-name/
  pyproject.toml
  config.py          # Configuration (env-overridable)
  server.py          # Entry point
  routes/            # API routes (FastAPI)
  temporal/          # Workflow orchestration (if applicable)
  tests/
  data/              # Local data (gitignored if large)

Python Library

project-name/
  pyproject.toml
  src/
    package_name/
      __init__.py
      modules...
  tests/
  examples/

API Design

FastAPI for all HTTP services
Pydantic models for request/response validation
Bind to localhost by default. Expose via reverse proxy when needed.
Health endpoint at GET /api/health
JSON responses. Consistent error format.

AI / ML

Ollama

Default model: llama3 for generation. Default embeddings: nomic-embed-text. Always gate LLM calls behind deterministic classification. If decompose or regex can answer the question, do not call the LLM.

Embeddings / Vector Search

Qdrant for vector storage. Embed with consistent model per collection. Do not mix embedding models within a collection. Test retrieval quality against known-good queries before deploying.

decompose Integration

Use decompose as the first stage of any document processing pipeline. decompose is deterministic. Its output is ground truth for the pipeline. Do not override its classifications with LLM opinions.

Infrastructure

All services run locally. The platform runs as a unified Docker Compose stack.

Image layering mirrors the architecture:

decompose (L0: deterministic foundation)
  → engine (L1: perception)
    → ops (L2: operations)
      → verticals (L3: domain-specific)

Ollama runs on the host, not in a container. Containers reach it via host networking. Each layer adds capability but is never required by the layer below it.

Documentation

FOUNDATION.md is the identity document. It is not modified casually.
CLAUDE.md at the root provides AI instructions for all projects. Each project may have its own that adds project-specific context without contradicting the root.
README.md per project: what it is, how to run it, how to develop on it.
Do not generate documentation for code you did not write or change.

The Test

Every change, every feature, every decision is evaluated by the same question from the foundation:

"Does this reveal structure or introduce noise?"

If it reveals structure, build it. If it introduces noise, don't.

The Logos Structure

The foundational thesis of echology. Mission, values, structural principles, and system identity.

Platform Validation

The system verifies itself. Three engines tested against the platform's own corpus. Every number from ops.db.

Built with these standards

Every echology product follows these engineering standards. See the system in action on your own data.

Request an Audit