How geogdog/venture works
Project type and purpose
• Type: A CLI-based, open-source tool for bootstrapping and managing project skeletons.
• Purpose: Generate skeleton code, initialize Git repos, and provide shell completion helpers.
File structure
• Top level:
– README.md, LICENSE, Makefile, pyproject.toml (packaging/build).
– doc/adr (Architecture Decision Records) – documents design choices like “use GitPython.”
– tests/ – unit tests for each module.
– venture/ – application source:
• cli.py (command parsing & orchestration)
• completion.py (shell‐completion support)
• Key patterns:
– Single process CLI app with modular subcommands.
– Separation of concerns: parsing (cli.py), completion (completion.py), docs (doc/adr), tests.
Extract insights from README
• Core features:
– “create skeleton code”
– “manage projects in a sane way”
• Implied dependencies: filesystem I/O, Git integration, shell environments.
Main components
a. User / Shell
– Initiates commands (“venture init”, “venture new”, etc.)
b. CLI Parser (venture/cli.py)
– Parses commands, delegates to subcommands or core services
c. Core Generator Service
– Implements skeleton‐scaffolding logic
– Reads/writes files on local FS
– Invokes GitPython for repo init, commits
d. Shell‐Completion Module (venture/completion.py)
– Generates shell scripts for bash/zsh/fish
– Hooks into user’s shell profile
e. Packaging & Build (Makefile, pyproject.toml)
– Defines how to install, build, run tests, publish
f. Tests (tests/)
– Validates CLI parsing, code generation, completion outputs
g. Documentation (doc/adr/)
– Illustrates architectural decisions (external to runtime)
Relationships & data flows
• CLI Parser → Core Generator (invoke scaffolding routines)
• Core Generator → Filesystem (create directories & files)
• Core Generator → GitPython (initialize repo, commit)
• CLI Parser → Shell‐Completion Module (on “venture completion” command)
• Shell‐Completion Module → User’s Shell (writes completion scripts)
• Tests → CLI Parser, Core Generator, Completion (calls internal APIs)
Architectural patterns & design principles
• Modular layering: CLI layer, service layer, infrastructure (FS, Git), testing.
• Single‐responsibility modules: each .py file handles one concern.
• ADR-driven decisions (e.g., using GitPython) kept in doc/adr for traceability.