src.services.architecture_services

Module Contents

src.services.architecture_services.SECTION_NAMES = ['project overview', 'entry points', 'services', 'routers', 'modules and packages', 'internal...

src.services.architecture_services.MANUAL_EDIT_MARKER = '.. AUTODOC ARCHITECTURE DRAFT'

exception src.services.architecture_services.ArchitectureAnalysisError(message: str, status_code: int = 422)

Bases: RuntimeError

Raised when architecture analysis cannot proceed or yields no usable evidence.

status_code = 422

exception src.services.architecture_services.ArchitectureApprovalError(message: str, status_code: int = 422)

Bases: RuntimeError

Raised when an architecture draft cannot be approved.

status_code = 422

exception src.services.architecture_services.ArchitectureOverwriteRequiredError(message: str)

Bases: ArchitectureApprovalError

Raised when approval would overwrite existing manual content without confirmation.

class src.services.architecture_services.ArchitectureFinding

An observed fact or inferred architecture relationship.

finding_type: str

name: str

classification: str

description: str

evidence_paths: list[str] = []

confidence_level: str | None = None

to_dict() → dict

Convert the documentation gap to a dictionary. :param self: Instance containing gap details. :type self: DocumentationGap

Returns:: Serialized gap fields for review.
Return type:: dict

class src.services.architecture_services.AnalysisGap

Incomplete or ambiguous architecture analysis for a section.

section_name: str

gap_type: str

description: str

recommended_review_action: str = ''

to_dict() → dict

Return a dictionary representation of the finding.

Returns:: Serialized finding fields, including type, name, classification, evidence paths, and confidence level.
Return type:: dict

class src.services.architecture_services.ArchitectureSection

One required section of the architecture draft.

section_name: str

status: str

summary: str

findings: list[ArchitectureFinding] = []

confidence_level: str = 'not_applicable'

gaps: list[AnalysisGap] = []

property observed_count: int

Return the number of findings classified as observed.

Returns:: Count of findings with classification set to “observed”.
Return type:: int

property inferred_count: int

Return the number of findings classified as inferred.

Parameters:: None.
Returns:: Count of findings with classification set to “inferred”.
Return type:: int

to_summary_dict() → dict

Return a compact summary representation of this section.

Returns:: Mapping containing section name, status, confidence level, and observation counts.
Return type:: dict

src.services.architecture_services.generate_draft_id() → str: Generates a unique, sortable architecture draft id.

src.services.architecture_services.architecture_draft_paths(repo_path: str, provider: str, draft_id: str) → tuple[str, str]: Returns the (rst_path, json_metadata_path) artifact locations for a draft id.

src.services.architecture_services.is_autodoc_generated_content(content: str) → bool: Returns True when content was previously written by an approved Auto Doc draft.

src.services.architecture_services.generate_architecture_draft(provider: str, repo_url: str, token: str, branch: str, target_folders: list[str] | None, output_path: str, include_diagrams: bool, reuse_existing_docs: bool, progress_callback=None) → dict

Analyzes a repository and produces a reviewable architecture documentation draft.

Generation is read-only: it never commits, writes, or publishes to the target repository.

src.services.architecture_services.find_architecture_draft(repo_path: str, provider: str, draft_id: str) → dict | None: Searches this repository’s run artifact history for a generated draft’s metadata.

src.services.architecture_services.apply_architecture_approval(provider: str, repo_url: str, token: str, branch: str, draft_id: str, output_path: str, overwrite_existing: bool, approval_note: str | None = None) → dict

Applies an approved architecture draft to the target repository documentation tree.

Raises ArchitectureOverwriteRequiredError when existing manual content would be replaced without explicit overwrite confirmation.