Skip to content

Developer Guide

Welcome to the DynVision Developer Guide! This section provides comprehensive resources for contributors, maintainers, and AI assistants (like Claude Code) working on the DynVision codebase.

Purpose

The Developer Guide serves multiple audiences:

  • Contributors: Understand architecture, follow coding standards, learn workflows
  • Maintainers: Track TODOs, plan features, manage dependencies
  • AI Assistants: Comprehensive context for Claude Code and similar tools
  • Researchers: Understand design decisions and biological motivations

Organization

The Developer Guide is organized into four main sections:

📋 Planning

Forward-looking documentation tracking what needs to be done:

  • Documentation TODOs: Open documentation tasks
  • Missing pages and sections
  • Doc/code consistency issues

  • Content-quality improvements

  • Development Roadmap: Planned improvements to the toolbox

  • Compatibility & packaging (Python 3.12/3.13, templates)
  • Configuration, parameters, and logging
  • Workflow, reproducibility, performance, and testing

When to use: Before starting new work, check these files to avoid duplication and align with project priorities.

📖 Guides

How-to information for developers and AI assistants:

  • AI Style Guide: START HERE - Core principles for AI-assisted research software development
  • Research software best practices (scientific correctness, reproducibility, performance)
  • Investigation → Analysis → Implementation workflow
  • Code organization, documentation, testing, error handling
  • Communication and collaboration guidelines
  • General principles applicable to any research software project

  • Use this to prime AI assistants before working on any task

  • Claude Code Guide: DynVision-specific context for Claude Code (formerly CLAUDE.md)

  • Project overview and design philosophy
  • Development commands (setup, running experiments, code quality)
  • Detailed architecture (multi-inheritance, base classes, components)
  • Configuration system and parameter handling
  • Common workflows (adding models, experiments, recurrent connections)
  • Known issues and quick reference

  • Use this after the AI Style Guide for project-specific details

  • Documentation Style Guide: Standards for writing documentation

  • Documentation philosophy and structure
  • Writing style and formatting
  • Code examples and API documentation
  • Diagrams and visual elements

  • Review checklist

  • Research Software: Considerations for Software Dev in Research

  • Expert research software developer agent persona
  • Code review and analysis framework (scientific correctness, architecture, performance, quality, documentation)
  • Structured deliverables format (executive summary, detailed analysis, code examples, roadmap)
  • Specialized areas (scientific computing optimization, neural networks, computational neuroscience)
  • Software engineering best practices (testing, documentation, reproducibility, sustainability)

  • Project-specific applications and context adaptation

  • Software Patterns: Design patterns for scientific computing

  • Architectural patterns (Layered, Pipeline, Domain-Driven Design, Event-Driven)
  • Creational patterns (Factory, Abstract Factory, Builder, Singleton, Prototype)
  • Structural patterns (Adapter, Facade, Composite, Decorator, Bridge)
  • Behavioral patterns (Strategy, Observer, Command, Template Method, State, Iterator, Visitor)
  • Scientific computing patterns (Computation Graph, Lazy Evaluation, Parameter Management, Data Pipeline, Experiment Tracking)

When to use:

  • AI Assistants: Start with AI Style Guide → Claude Code Guide → other guides as needed
  • Human Developers: Reference guides when developing features, writing docs, or onboarding

🔧 Dependencies

Knowledge about external frameworks and libraries:

  • Snakemake: Workflow management system
  • Fundamentals of Snakemake (rules, wildcards, config)
  • DynVision workflow structure
  • Writing new rules and experiments
  • Debugging workflows

  • Cluster integration

  • PyTorch Lightning: Deep learning framework

  • Lightning integration in DynVision
  • LightningModule structure
  • Training loops and callbacks
  • Logging and checkpointing

  • Multi-GPU training

  • FFCV: Fast data loading library

  • What FFCV is and when to use it
  • Installation and setup
  • Creating .beton files
  • Performance considerations
  • Troubleshooting

When to use: Learning about framework capabilities, debugging integration issues, or optimizing performance.

For New Contributors

Recommended reading order:

  1. Start with Claude Code Guide for project overview
  2. Reference Research Software for design guidance
  3. Consult Documentation Style Guide when writing docs
  4. Review Documentation TODOs to find contribution opportunities
  5. Check Development Roadmap for aligned feature work

For AI Assistants

Required Reading Order:

  1. AI Style Guide first - Establishes core principles for research software development
  2. Claude Code Guide second - Provides DynVision-specific architecture and conventions

The AI Style Guide teaches you how to approach research software tasks with emphasis on:

  • Scientific correctness and reproducibility
  • Investigation → Analysis → Implementation workflow
  • Performance optimization strategies
  • Documentation and testing standards
  • Communication with researchers

The Claude Code Guide provides project-specific context:

  • Complete architecture with inheritance diagrams
  • All parameter aliases and conventions
  • Common workflows with examples
  • Known issues and inconsistencies

Together, these guides minimize the need for extensive code reading while ensuring accuracy and adherence to best practices.

For Maintainers

Track project health via:

Both files group items by area for easy scanning.

Most Referenced:

Dependency Docs:

Contributing Workflow

  1. Find a Task: Check Documentation TODOs or Development Roadmap
  2. Understand Context: Read Claude Code Guide architecture section
  3. Follow Standards: Reference Documentation Style Guide
  4. Implement: Use codebase patterns for guidance
  5. Test: Add tests (see Roadmap #29-#31 for test infrastructure plans)
  6. Document: Update relevant docs following style guide
  7. Review: Check against Claude Code Guide for consistency

Keeping Documentation Current

This Developer Guide should be updated:

Questions or Feedback?

  • Check Documentation TODOs to see if your question is a known issue
  • Open a GitHub issue for new documentation needs
  • Contact maintainers: robin.gutzen@nyu.edu

Last Updated: 2025-10-23

This Developer Guide is maintained by the DynVision team and is designed to evolve with the project. Contributions and suggestions are welcome!