frictionless-architect

Imported from wolffy-au/frictionless-architect (AGENTS.md). Install upstream with npx skills add wolffy-au/frictionless-architect. Copyright stays with the author.

002-neo4j-schema-ui Development Guidelines

Auto-generated from all feature plans. Last updated: 2026-04-04

Active Technologies

• Python 3.12 (per pyproject.toml). + FastAPI 0.128.x, uvicorn, neo4j 5.x driver, python-dotenv/pydantic for settings and payload validation, httpx/pytest for endpoint tests, ruff/pyright/mypy for linting. (002-neo4j-schema-ui)

• Neo4j 5 cluster for live schema metadata; canonical ArchiMate schema files under sample-data/schema and the enriched sample-data/sample-00/Test Model Full.xml drive the payloads. The visualiser caches aggregated JSON payloads in .cache/visualiser for offline resilience. (002-neo4j-schema-ui)

• Python 3.12 (per pyproject.toml and repo README). + FastAPI 0.128.x, uvicorn for serving, neo4j 5.x driver, python-dotenv, pydantic v2 for settings/data validation, httpx/pytest for tests, ruff/pyright/mypy for quality checks. (002-neo4j-schema-ui)

Project Structure

src/
tests/

Commands

cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .

Code Style

Python 3.12 (per pyproject.toml and repo README).: Follow standard conventions

Recent Changes

• 002-neo4j-schema-ui: Added Python 3.12 (per pyproject.toml). + FastAPI 0.128.x, uvicorn, neo4j 5.x driver, python-dotenv/pydantic for settings and payload validation, httpx/pytest for endpoint tests, ruff/pyright/mypy for linting.

• 002-neo4j-schema-ui: Added Python 3.12 (per pyproject.toml and repo README). + FastAPI 0.128.x, uvicorn for serving, neo4j 5.x driver, python-dotenv, pydantic v2 for settings/data validation, httpx/pytest for tests, ruff/pyright/mypy for quality checks.

Development guide

This file orients agents and people doing development work on this repo. If you only want to understand or run the project, read README.md instead.

The sections above this marker are regenerated by .specify/scripts/bash/update-agent-context.sh — do not hand-edit them; add durable guidance here, inside the manual block.

Toolchain

• Poetry only for dependency management — never uv (see ARCHITECTURE.md §5). poetry install installs the project and all groups (dev, tests, lint, docs).
• Python 3.12 (supported range >=3.11,<3.14).
• Lint / types: ruff, pyright, mypy. Tests: pytest (+ pytest-cov), behave.
• Run everything through poetry run … or poetry env activate.

Repository layout

• Root — governance and orchestration only: PROJECT_SPECIFICATION.md, .specify/memory/constitution.md, ARCHITECTURE.md, TECHNICAL.md, RELEASE.md.
• src/frictionless_architect/ — application code (visualizer/, schema/).
• tests/ — mirrors the src/ package layout; tests/unit/<pkg>/test_<mod>.py for src/frictionless_architect/<pkg>/<mod>.py. Also tests/api/ (in-process FastAPI) and tests/features/ (behave). See TECHNICAL.md → "Testing Layout".
• .claude/skills/ and .claude/agents/ — the skill and subagent catalogs (below); tracked in git despite living under .claude/ (see .gitignore's .claude/ block).
• .specify/ — Spec Kit machinery; specs/ — feature specs.

Working on the code

poetry install                       # project + all dependency groups
poetry run pytest                    # full test suite
bash scripts/pre_commit_checks.sh    # fast gate: lock refresh, pymarkdown, ruff, pyright, mypy, tests/unit/
bash scripts/pre_merge_checks.sh     # + behave, coverage-gated pytest, frontend UI harness

Pre-commit hooks are installed (.pre-commit-config.yaml): fast autofix on commit, type/test suite on push, Conventional Commits check on the message.

Known environment quirks

• drvfs/9p workspace, chmod/chown → EPERM: in this devcontainer, /workspaces/frictionless-architect is a 9p bind mount off a Windows drive (aname=drvfs;path=C:\). Every file shows as mode 0777 owned by vscode regardless of the writing UID, and any chmod/chown on a path under the workspace fails with Operation not permitted — including chmods a tool runs internally as part of an atomic tempfile → chmod → rename write (this is what breaks specify integration upgrade / specify init, and the Claude Code integration's install step; see .devcontainer/post-create.sh). Prefix the failing command with sudo — running as root sidesteps the drvfs UID-mapping check that causes the EPERM, e.g. git submodule update --init <path> (which chmods .git/config.lock) fails unprivileged but succeeds under sudo. sudo -n true works passwordless in this container. If a partial/interrupted operation left debris behind (e.g. a half-cloned submodule directory), remove it first (rm -rf <path>) before retrying — a non-empty destination fails the retry with an unrelated error. Root's global git config is separate from the normal user's; if you hit "detected dubious ownership", also run sudo git config --global --add safe.directory <path> (or '*') before the sudo git … command that needs it.

Conventions

• Conventional Commits, enforced by commitizen. Use the commit-message skill for the ruleset and commit-auditor to check a branch before a PR. Tags are v$version; cz bump owns CHANGELOG.md and the tag (version_provider = "scm").
• Work on feature/** or bugfix/** branches — never directly on main or develop.
• Spelling of "visualiser": code identifiers, module/package names, paths, route segments and the wiki topic slug use visualizer (-z-, matching the Python/FastAPI ecosystem and the future schema-visualizer-api package). Running prose uses the en-GB "visualiser" (-s-). Both spellings appearing in one sentence (e.g. "the visualiser lives in visualizer/") is intentional, not a typo.
• Feature work is spec-driven: speckit-specify → speckit-plan → speckit-tasks → speckit-implement, against .specify/memory/constitution.md.
• Releases follow RELEASE.md (or the release-runner agent).

Skills & Workflows

Available skills/workflows are cataloged in .claude/skills/README.md. Invoke each by its directory name (e.g. speckit-plan, fork-sync).

Subagents are cataloged in .claude/agents/README.md (e.g. quality-uplift, coverage-uplift, acceptance-author, docs-uplift, refactor-analyst, spec-alignment, adr-auditor, vulnerability-remediator, release-runner, commit-auditor).

Architecture decisions are recorded as MADR files under docs/adr/ — ARCHITECTURE.md is the narrative, the ADR log is the index. File an ADR for any load-bearing choice; adr-auditor sweeps for decisions that were made without one. The end-to-end release procedure lives in RELEASE.md.