# v0.7.4 — Internal Architecture Refactor

## Context

RAC has grown from a small CLI utility into a structured product knowledge toolkit.

The codebase now supports:

- Multiple artifact types
- Repository inspection
- Artifact improvement
- Relationship discovery
- Relationship validation
- JSON outputs
- Future interactive consumers such as RAC Explorer

Early implementations prioritized shipping capabilities quickly, which resulted in
most implementation files living directly under `src/rac`.

As RAC moves toward Explorer and richer repository intelligence, clearer internal
boundaries are required.

This release introduces an internal package structure that reflects RAC's long-term
architecture.

## Goals

- Improve maintainability before RAC Explorer development.
- Separate product logic from command-line presentation.
- Establish clear ownership boundaries.
- Preserve existing CLI behavior.
- Avoid introducing new user-facing functionality.

## Requirements

### Introduce Layered Package Structure

Refactor `src/rac` into explicit architectural areas:

```text
src/rac/
├── cli.py
├── core/
├── services/
├── output/
└── explorer/
```

### CLI Layer

Keep command handling in the single thin adapter:

```text
src/rac/cli.py
```

Responsibilities:

- Parse command arguments.
- Call service-layer APIs.
- Format command responses.
- Return appropriate exit codes.

The CLI layer must not contain repository intelligence.

Per-command CLI modules (`src/rac/cli/<command>.py`) are deferred until a command
develops genuine command-specific complexity. Symmetry with the service layer is
not, on its own, a reason to split.

---

### Core Layer

Introduce:

```text
src/rac/core/
```

Responsibilities:

- Markdown parsing.
- Artifact models.
- Validation primitives.
- Shared domain behavior.

Core should not know about:

- CLI arguments.
- Terminal formatting.
- Explorer.

---

### Service Layer

Introduce:

```text
src/rac/services/
```

Responsibilities:

- Repository analysis.
- Artifact improvement.
- Relationship operations.
- Portfolio intelligence.

Services provide stable APIs consumed by:

- CLI
- Explorer
- Tests
- Future integrations

---

### Output Layer

Introduce:

```text
src/rac/output/
```

Responsibilities:

- Human-readable formatting.
- JSON formatting.
- Templates.

Output concerns should not leak into core logic.

---

### Explorer Preparation

Create the package boundary:

```text
src/rac/explorer/
```

This package may initially remain empty.

Explorer must consume existing RAC services rather than implementing independent
repository analysis.

---

## Migration Requirements

Existing commands must continue working:

```bash
rac inspect
rac improve
rac relationships
rac schema
rac init
```

Existing JSON contracts must remain unchanged.

Existing tests must continue passing.

Existing `rac.*` import paths must keep resolving. Implementation moves into the
layer packages, and thin compatibility shims remain at the previous module paths
so consumers and tests are not forced to migrate.

No breaking user-facing changes are allowed.

## Non-Goals

This release does not:

- Add RAC Explorer.
- Change artifact schemas.
- Add repository intelligence.
- Modify command behavior.
- Introduce new CLI commands.

## Validation

Implementation is complete when:

- All existing tests pass.
- CLI commands behave identically.
- Business logic exists outside CLI modules.
- Services can be invoked without command-line dependencies.
- Explorer can be implemented as a consumer.

## Success Measures

- New commands have an obvious implementation location.
- Core RAC capabilities are reusable outside the CLI.
- Explorer development does not require moving existing logic.
- Future integrations can depend on RAC services directly.
```