ddr-docs 0.1.0

FileMaker DDR to Documentation Generator

FM2Web Desktop

FM2Web is a FileMaker DDR extraction pipeline with a Tauri desktop app that bundles the Analyzer backend and runs fully offline.

Prerequisites

Install these before first startup.

macOS (Homebrew)

brew install python@3.11 node
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

Windows (winget)

winget install Rustlang.Rustup
winget install Python.Python.3.11
winget install OpenJS.NodeJS.LTS

Ubuntu/Debian

sudo apt update
sudo apt install -y curl python3 python3-venv python3-pip nodejs npm
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

Verify

rustc --version
python --version
node --version
npm --version

Optional but required for backend bundling:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install pyinstaller

Alternative (no venv, via pipx):

brew install pipx
pipx install pyinstaller

Tauri First Start Up (Recommended)

1) Install Desktop Dependencies

cd desktop
npm install

2) Build the Backend Bundle (One-Time Per OS)

This creates a standalone backend executable that Tauri launches on app start.

macOS/Linux:

cd /Users/marcusswift/python/FM2Web
python3 -m PyInstaller analyzer/launcher.py \
  --name fm2web-backend \
  --onefile \
  --clean \
  --noconfirm \
  --distpath desktop/src-tauri/resources/backend
chmod +x desktop/src-tauri/resources/backend/launch_backend.sh

Windows (PowerShell):

cd C:\path\to\FM2Web
python -m PyInstaller analyzer/launcher.py `
  --name fm2web-backend `
  --onefile `
  --clean `
  --noconfirm `
  --distpath desktop/src-tauri/resources/backend

3) Run Tauri

cd desktop
npm run tauri dev

The app launches the bundled backend automatically.

DDR Review runs extraction on demand and stores results in a per-workspace SQLite database under the app data directory.

If you want preloaded docs during development or to ship with a build, put them in:

• ai_docs/context/extracted_docs

Example generator:

python3 -m ddr_docs generate /path/to/your.ddr.xml -o ai_docs/context/extracted_docs

Desktop Build (Release)

cd desktop
npm run build
npm run tauri build

Agent CLI Install

For DevFlow/OpenClaw-style agents on this machine, the stable CLI entrypoint is:

• Wrapper on PATH: /Users/devflow/bin/ddr-docs
• Backing venv CLI: /Users/devflow/repos/FM2Web/.agent-venv/bin/ddr-docs

The wrapper is the preferred invocation path:

ddr-docs --help
ddr-docs generate /path/to/file.xml -o /path/to/extracted_docs --persist-sqlite --sqlite-path /path/to/fm2web.sqlite
ddr-docs analyze --help

This install is backed by the FM2Web repo at:

• /Users/devflow/repos/FM2Web

Core Features

• DDR extraction pipeline: ingest → parse → extract → render → index → report
• Canonical JSON + Markdown outputs for migration planning
• Streamlit UI for local extraction/browsing
• Analyzer API for dependency tracing and retrieval
• Offline-first with explicit policy controls

CLI (Optional)

Install from a checkout:

python3 -m pip install .
# or for editable local development
python3 -m pip install -e .

Generate documentation directly from DDR XML:

python -m ddr_docs generate /path/to/your.ddr.xml -o /path/to/output

Output includes:

• json/ canonical artifacts
• 00_MASTER_SUMMARY.md and other Markdown summaries
• diagrams/ relationship diagrams
• index/ search index
• reports/ coverage + warnings
• manifest.json run metadata

Streamlit UI (Optional)

streamlit run ui/streamlit_app.py

Analyzer API (Optional)

python -m analyzer.app

Set:

• FM2WEB_AUTH_TOKEN
• FM2WEB_EXTRACTED_DOCS_PATH

Key Paths

• desktop/ Tauri app (React + Rust)
• desktop/src-tauri/resources/backend/ bundled backend launcher + exe
• analyzer/ FastAPI backend + graph services
• ddr_docs/ CLI pipeline + renderers
• playground/ scenario test harnesses for features
• scripts/ legacy extractors
• ui/ Streamlit UI
• ai_docs/context/source_docs/ default DDR input location
• ai_docs/context/extracted_docs/ default output location

Workspace Layout

Workspaces isolate each DDR import into its own SQLite database and extracted docs tree.

• Workspace store: {app_config_dir}/fm2web-workspaces.json
• Runtime config: {app_data_dir}/runtime/active_workspace.json
• Workspace data: {app_data_dir}/workspaces/{workspace-slug}/ with fm2web.sqlite3 and ai_docs/extracted_docs/
• CLI (no config file): uses ai_docs/context/extracted_docs under the current working directory

See docs/workspace_layout.md and docs/workspace_data_model.md for the full layout and config handshake details.

Packaging and PyPI release

Build and validate distributables locally:

python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*

Upload to PyPI with an environment variable, without storing credentials in the repo:

export PYPI_TOKEN=pypi-...
./scripts/publish_pypi.sh

Useful dry run against TestPyPI:

export PYPI_TOKEN=pypi-...
./scripts/publish_pypi.sh --repository testpypi

Testing & Development

Playground Scenarios

Run scenario-based tests for specific features:

# Parsing & normalization scenarios
python3 playground/parsing-normalization/playground.py <scenario-slug>

# See playground READMEs for available scenarios

The playground harnesses work from any working directory and automatically set up the module import paths.

Notes

• For detailed Tauri backend bundling, see desktop/BACKEND_BUNDLE.md.
• Offline policy details: OFFLINE_POLICY.md.

License

MIT