BARKLY DOCS v3

Functional Requirements Document

A Project Understanding and Documentation System for Human-Centered Software

1. Purpose

Barkly Docs SHALL analyze software projects and transform their source structure, documentation, configuration, and relationships into understandable, human-readable project documentation.

Barkly Docs SHALL progress beyond documenting individual files, classes, and functions.

The system SHALL be capable of helping a human understand:

What is this project?

What technologies does it use?

How is it structured?

What languages are present?

What are the major components?

How do the components relate?

What does each component appear to do?

What depends on what?

Where are the important interfaces?

What documentation describes the system?

Which parts are known, detected, inferred, or unknown?

How does the project fit together as a whole?

The source project SHALL remain authoritative.

AI-assisted interpretation MAY be used to explain project structure and apparent intent, but SHALL NOT replace deterministic source analysis.

Barkly Docs is therefore not merely a code documentation generator.

Barkly Docs is a project understanding system.

The documentation generator is one layer of the system.

Language readers provide the source-analysis layer.

The Barkly Project Model provides the normalized representation.

The relationship engine provides structural understanding.

The project graph provides a connected representation of the system.

Deterministic generation produces reproducible documentation.

Optional CYN-X interpretation MAY provide additional human-oriented explanations.

The Barkly website provides the human-facing exploration layer.

2. Core Architecture

Barkly Docs SHALL use a layered architecture.

SOURCE PROJECT

│

▼

PROJECT DISCOVERY

│

├── Language Detection

├── File Detection

├── Documentation Detection

├── Configuration Detection

├── Build-System Detection

└── Git Detection

│

▼

LANGUAGE / FORMAT READERS

│

├── Python

├── JavaScript

├── TypeScript

├── Rust

├── Ruby

├── Java

├── C++

├── Astro

├── HTML

├── CSS

└── Markdown

│

▼

BARKLY PROJECT MODEL

│

▼

RELATIONSHIP ENGINE

│

▼

PROJECT GRAPH

│

▼

PROJECT INTERPRETATION

│

├── Deterministic Analysis

│

└── Optional CYN-X Interpretation

│

▼

BARKLY DOCUMENTATION

│

├── Markdown

├── HTML

└── JSON

│

▼

BARKLY WEBSITE / OTHER OUTPUTS

Language-specific readers SHALL perform source-specific analysis.

Readers SHALL NOT independently generate final documentation.

All readers SHALL produce normalized data for the Barkly Project Model.

3. Project Discovery

FR-001 — Project Discovery

Barkly Docs SHALL accept a project directory as its primary input.

It SHALL recursively discover relevant project files.

The discovery system SHALL identify, where applicable:

source files

documentation

configuration

package manifests

dependency manifests

build configuration

test files

static assets

generated files

Git metadata

language indicators

framework indicators

project metadata

Barkly Docs SHOULD distinguish source-controlled files from generated or ignored files where sufficient information exists.

4. Multi-Language Project Analysis

FR-002 — Multi-Language Analysis

Barkly Docs SHALL support projects containing multiple programming languages, markup languages, configuration formats, and documentation formats.

Initial programming-language support SHALL include:

Python

JavaScript

TypeScript

Rust

Ruby

Java

C++

Existing project/web support SHALL include:

Astro

HTML

CSS

Markdown

A project MAY contain any combination of supported languages.

Barkly Docs SHALL analyze supported languages as parts of one project rather than treating each language as an isolated project.

For example:

BARKLY PROJECT

Rust

└── core system

C++

└── hardware / native component

Python

└── tooling / automation

TypeScript

└── application logic

JavaScript

└── runtime / web behavior

Markdown

└── documentation

The final Project Model SHALL represent these as components of the same project.

Additional languages MAY be added without redesigning the core Project Model.

5. Language Adapter Architecture

FR-003 — Language Readers

Each supported programming language SHALL have a dedicated reader or adapter.

The architecture SHOULD support a structure similar to:

barkly_docs/

│

├── readers/

│ ├── python.py

│ ├── javascript.py

│ ├── typescript.py

│ ├── rust.py

│ ├── ruby.py

│ ├── java.py

│ ├── cpp.py

│ ├── astro.py

│ ├── html.py

│ ├── css.py

│ └── markdown.py

│

├── model/

├── relationships/

├── graph/

├── interpretation/

├── rendering/

├── validation/

└── cli/

Each reader SHALL translate language-specific structures into the common Barkly Project Model.

Readers SHALL be independently testable.

A failure in one reader SHOULD NOT prevent other supported readers from analyzing the remainder of a project.

6. Common Barkly Project Model

FR-004 — Common Project Model

Language-specific readers SHALL NOT directly generate final documentation.

They SHALL produce normalized project objects.

The common model SHALL support objects including, where applicable:

Project

File

7. Python Reader

FR-005 — Python Static Analysis

The Python reader SHALL analyze Python source statically where practical.

It SHALL identify, where supported:

modules

packages

imports

classes

methods

functions

parameters

return annotations

decorators

constants

assignments

docstrings

type annotations

exceptions

module relationships

function relationships

The Python reader SHALL use the Python AST or another static representation where practical.

Source code SHALL NOT need to be imported or executed merely to document it.

8. JavaScript Reader

FR-006 — JavaScript Analysis

The JavaScript reader SHALL identify, where supported:

modules

imports

exports

functions

arrow functions

classes

methods

variables

constants

objects

calls

comments

documentation

relationships

The reader SHOULD distinguish common module/export patterns where determinable.

9. TypeScript Reader

FR-007 — TypeScript Analysis

The TypeScript reader SHALL additionally recognize, where supported:

interfaces

types

enums

generics

type annotations

access modifiers

decorators

namespaces

modules

imports

exports

classes

methods

functions

type relationships

TypeScript-specific structures SHALL remain distinguishable from equivalent JavaScript structures when that distinction is meaningful.

10. Rust Reader

FR-008 — Rust Analysis

The Rust reader SHALL analyze Rust source statically where practical.

It SHALL identify, where supported:

crates

modules

functions

structs

enums

traits

implementations

methods

constants

statics

type aliases

generics

lifetimes where determinable

macros

attributes

visibility

imports

exports

dependencies

tests

documentation comments

The reader SHALL identify relationships such as:

Module

└── contains

├── Struct

├── Enum

├── Trait

└── Function

Struct

└── implemented by

└── impl block

Trait

└── implemented by

└── Type

Cargo metadata SHOULD be recognized where available.

11. Ruby Reader

FR-009 — Ruby Analysis

The Ruby reader SHALL analyze Ruby source statically where practical.

It SHALL identify, where supported:

modules

classes

methods

singleton methods

constants

attributes

blocks

mixins

includes

extensions

requires

dependencies

documentation comments

inheritance

method relationships

The reader SHOULD recognize common Ruby project structures including Gemfiles and gem metadata where available.

12. Java Reader

FR-010 — Java Analysis

The Java reader SHALL analyze Java source statically where practical.

It SHALL identify, where supported:

packages

classes

interfaces

enums

records

methods

constructors

fields

annotations

generics

inheritance

implementations

imports

dependencies

visibility

exceptions

documentation comments

tests

The reader SHOULD recognize common Java project structures and build metadata where available.

Initial build-system awareness SHOULD include common project indicators such as:

Maven

Gradle

13. C++ Reader

FR-011 — C++ Analysis

The C++ reader SHALL analyze C++ source statically where practical.

It SHALL identify, where supported:

source files

header files

namespaces

classes

structs

unions

functions

methods

constructors

destructors

templates

type aliases

enums

macros

includes

declarations

definitions

inheritance

access modifiers

constants

dependencies

The reader SHOULD distinguish declarations from definitions where determinable.

Build-system awareness SHOULD recognize common project indicators where available, including:

CMake

Make

Ninja

other supported build metadata

C and C++ MAY share implementation infrastructure where practical, but C++ SHALL remain a first-class supported language.

14. Astro Reader

FR-012 — Astro Analysis

The Astro reader SHALL understand the mixed structure of Astro files.

It SHALL distinguish, where possible:

Astro File

│

├── Frontmatter

│ └── JavaScript / TypeScript

│

├── Template

│ ├── HTML

│ ├── Astro Components

│ └── Expressions

│

└── Client Script

└── JavaScript / TypeScript

It SHALL identify, where supported:

pages

routes

layouts

components

imports

props

frontmatter

scripts

links

metadata

component relationships

This is particularly important for the Barkly website itself.

15. HTML Reader

FR-013 — HTML Analysis

The HTML reader SHALL identify:

document structure

headings

navigation

links

forms

semantic elements

IDs

classes

metadata

embedded resources

HTML relationships SHOULD be represented in the Project Model where meaningful.

16. CSS Reader

FR-014 — CSS Analysis

The CSS reader SHALL identify:

stylesheets

selectors

classes

IDs

media queries

CSS variables

animations

keyframes

imports

stylesheet relationships

dependencies where determinable

17. Markdown Reader

FR-015 — Markdown Analysis

The Markdown reader SHALL identify:

headings

sections

links

lists

code blocks

tables

images

references

metadata

documentation relationships

Markdown SHALL be treated as project knowledge rather than merely another text file.

18. Static Analysis Safety

FR-016 — Safe Source Analysis

Barkly Docs SHALL prioritize static analysis.

Barkly Docs SHALL NOT require arbitrary target-project code to execute merely to document the project.

Target-project imports SHALL NOT be required for normal analysis.

Target-project execution SHALL NOT be silently performed.

If runtime execution is ever introduced as an optional capability, it SHALL be explicitly configured and separately controlled.

19. Evidence and Confidence

FR-017 — Evidence States

Barkly Docs SHALL distinguish between information that is:

DECLARED

DETECTED

INFERRED

UNKNOWN

The system SHALL NOT present inferred information as directly observed source facts.

Where practical, generated documentation SHOULD identify the source or evidence supporting significant claims.

20. Language Feature Normalization

FR-018 — Normalized Language Semantics

Barkly Docs SHALL normalize equivalent concepts across supported languages while preserving language-specific distinctions.

For example:

Python Class

Java Class

C++ Class

Rust Struct

Ruby Class

TypeScript Class

MAY all map to appropriate Project Model entities while retaining their original language and semantic type.

Likewise:

Python import

Java import

C++ include

Rust use

Ruby require

JavaScript import

MAY become normalized dependency relationships while preserving their original syntax and meaning.

21. Cross-Language Project Support

FR-019 — Cross-Language Projects

Barkly Docs SHALL support projects containing multiple supported programming languages.

The system SHALL be capable of representing relationships between languages when those relationships can be determined.

Examples include:

Python

│

└── invokes

│

▼

C++ library

Rust

│

└── exposes

│

▼

JavaScript binding

TypeScript

│

└── documents

│

▼

Rust service

Where a relationship cannot be reliably determined, Barkly Docs SHALL mark it as unknown rather than inventing a relationship.

22. Relationship Engine

FR-020 — Relationship Detection

Barkly Docs SHALL construct relationships between discovered project entities.

Relationships SHALL include, where determinable:

imports

exports

includes

calls

references

inheritance

implementation

composition

dependency

route ownership

component usage

documentation references

configuration relationships

test relationships

build relationships

The relationship engine SHALL operate on the normalized Project Model rather than being permanently tied to a single language.

23. Project Graph

FR-021 — Project Graph

Barkly Docs SHALL construct a project graph representing discovered entities and their relationships.

The graph SHOULD allow a human or downstream system to answer questions such as:

What depends on this component?

What does this module import?

Which files implement this interface?

Which tests relate to this component?

Which documentation describes this subsystem?

Which routes use this component?

Which build target contains this source?

Which parts of the project cross language boundaries?

The graph SHALL preserve source relationships without pretending that uncertain relationships are certain.

24. Project-Level Interpretation

FR-022 — Project Summary

Barkly Docs SHALL generate a project-level summary.

The summary SHOULD describe:

project identity

primary languages

frameworks

major components

directory structure

dependency structure

build systems

testing structure

documentation

major relationships

detected entry points

project status where determinable

FR-023 — Architectural Interpretation

Barkly Docs SHOULD derive higher-level architectural descriptions from deterministic project evidence.

Examples MAY include:

layered architecture

service architecture

CLI application

web application

library

monorepo

hardware/software project

documentation system

automation system

Architectural interpretations SHALL be identified as interpretations rather than direct source facts when they cannot be deterministically established.

25. Optional CYN-X Interpretation

FR-024 — AI-Assisted Interpretation

Barkly Docs MAY provide discovered project information to CYN-X or another approved AI system for human-oriented interpretation.

The AI layer SHALL receive structured evidence produced by Barkly Docs.

AI interpretation SHALL NOT replace deterministic analysis.

AI-generated claims SHOULD remain traceable to available project evidence.

AI output SHOULD clearly distinguish:

observed facts

reasonable interpretation

uncertainty

missing information

26. Source Authority

FR-025 — Source Authority

The source project SHALL remain authoritative.

Generated documentation SHALL NOT silently modify source code.

Generated interpretations SHALL NOT silently become source facts.

Barkly Docs SHALL preserve sufficient provenance to determine where generated information originated whenever practical.

27. Structured Documentation

FR-026 — Documentation Generation

Barkly Docs SHALL generate structured documentation from the normalized Project Model.

Generated documentation SHOULD include appropriate sections for:

project overview

architecture

languages

directory structure

components

modules

functions

classes

interfaces

dependencies

APIs

configuration

tests

relationships

source references

unknowns

analysis status

28. Machine-Readable Output

FR-027 — Machine-Readable Output

Barkly Docs SHALL support machine-readable project output.

The initial structured output format SHALL be JSON.

JSON output SHOULD contain:

project metadata

detected languages

project entities

relationships

dependencies

documentation entities

evidence states

source locations

analysis warnings

reader status

This output SHALL allow the Barkly website or future systems to consume Barkly Docs without re-analyzing the source project.

29. Language Regression Testing

FR-028 — Language Regression Tests

Each language reader SHALL have regression tests.

Tests SHALL verify that known source structures produce expected Project Model objects.

Regression coverage SHALL include representative fixtures for:

Python

JavaScript

TypeScript

Rust

Ruby

Java

C++

Astro

HTML

CSS

Markdown

Barkly Docs SHALL maintain its own regression suite.

The behavior of a target project SHALL NOT be treated as a prerequisite for Barkly D