# Open Fusion Code Quality

> Keep Open Fusion code maintainable with SOLID, DRY, clean architecture, and pragmatic TypeScript/NestJS design. Use when Codex designs modules, writes production code, refactors, reviews code quality, extracts abstractions, names services/adapters, or reduces duplication in the Open Fusion LLM gateway.

- Skill: `vinilana/open-fusion-code-quality` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vinilana/open-fusion-code-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinilana/open-fusion-code-quality/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vinilana (https://skillmd.com/u/vinilana)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinilana/open-fusion-code-quality

---


# Open Fusion Code Quality

## Required Context

Before judging design, read the relevant spec and ADR. For core architecture, read:

- `docs/PRD.md`
- `docs/adrs/0001-use-nestjs-backend.md`
- `docs/adrs/0003-use-vercel-ai-sdk.md`
- `docs/adrs/0007-provider-adapter-layer.md`

Use this skill with `open-fusion-tdd-cycle` for implementation changes.

## Design Principles

Apply SOLID pragmatically:

- Single Responsibility: controllers handle HTTP, config services handle config, adapters handle provider details, orchestration services handle orchestration policy.
- Open/Closed: new providers should be added by registering adapters, not editing controllers.
- Liskov Substitution: adapters must satisfy the same contract for success, stream, timeout, and error behavior.
- Interface Segregation: keep small interfaces for generation, streaming, config access, and secret resolution.
- Dependency Inversion: depend on internal abstractions, not concrete provider SDKs outside adapter modules.

Apply DRY after intent is clear:

- remove duplicated policy logic immediately;
- tolerate small duplicated tests until patterns stabilize;
- extract helpers only when they improve names and diagnostics;
- avoid generic abstractions for one provider or one endpoint.

## Open Fusion Boundaries

Keep these boundaries explicit:

- HTTP API: request validation, headers, status codes, SSE framing.
- Application orchestration: route resolution, delegate limits, final response lifecycle.
- Configuration: schema validation, env secret resolution, immutable runtime config.
- Provider adapters: Vercel AI SDK/provider specifics and error mapping.
- Observability/security: request ids, logging, redaction, auth, timeouts.

Crossing these boundaries should happen through typed interfaces.

## TypeScript Standards

- Prefer explicit domain types over loose `any`.
- Do not leave untyped locals that widen to `any` for provider, orchestration, or config results.
- Model config and API DTOs separately.
- Validate external input at boundaries before using typed runtime objects.
- Treat provider outputs as external input even when they came through an SDK type.
- Use discriminated unions for provider result/error variants when useful.
- Keep async cancellation/timeout behavior visible in function signatures or options.
- Extract shared domain types when the same request/client/config shape appears across services and Express request augmentation.

## NestJS Standards

- Keep controllers thin.
- Put business rules in injectable services.
- Use guards for auth, filters for error envelopes, interceptors/middleware for request id/logging where appropriate.
- Do not read env vars from controllers or orchestration services.
- Do not import provider SDK packages outside provider adapter modules.

## Code Smells To Fix

- provider-specific conditionals in controllers;
- repeated OpenAI error envelope construction;
- repeated config reference validation;
- raw secrets in logs or thrown errors;
- orchestration loops without hard backend limits;
- tests that only verify mocks were called;
- duplicated `AuthenticatedClient`-style shapes across services and request typings;
- provider payload casts without runtime validation;
- public or operational errors with misleading status/code semantics;
- abstractions named `Manager`, `Helper`, or `Util` without a clear domain role.

## Refactoring Rule

Refactor behind passing tests. If tests are missing, first add characterization tests for the behavior being preserved.