Project Structure

The Punch Card Project uses a standardized directory structure that follows best practices for Python projects. This organization ensures that the codebase is maintainable, scalable, and follows common Python project conventions.

Directory Structure

punch_card_project/
├── src/                    # Source code
│   ├── core/               # Core functionality modules
│   │   ├── punch_card.py   # Main punch card logic
│   │   ├── message_generator.py # Message generation
│   │   └── database.py     # Database interactions
│   ├── display/            # Display modules
│   │   ├── terminal_display.py  # Terminal UI
│   │   ├── gui_display.py  # GUI interface
│   │   └── display_adapter.py  # Display abstraction
│   └── utils/              # Utility functions
│       ├── settings_menu.py # Settings management
│       └── gui_integration.py # GUI utilities
├── docs/                   # Documentation
│   ├── research/           # Design research documents
│   └── technical/          # Technical documentation
├── tests/                  # Test files
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   ├── api/                # API and external service tests
│   ├── display/            # Display and UI tests
│   └── legacy/             # Older tests kept for reference
├── config/                 # Configuration files
│   └── templates/          # Configuration templates
├── data/                   # Data storage
│   └── local/              # Local data files
├── logs/                   # Log files
├── scripts/                # Utility scripts
├── versions/               # Archive of previous versions
│   ├── 0.1.0/              # The initial version
│   ├── 0.5.0/              # The GUI Update
│   ├── 0.5.1/              # The Documentation Update
│   └── 0.5.2/              # The Reorganization Update
├── secrets/                # API keys (git-ignored)
├── simple_display.py       # Main application entry point
├── update_api_key.py       # API key management utility
├── requirements.txt        # Python dependencies
└── README.md               # Project documentation

Key Components

Source Code (src/)

The src/ directory contains all the application code organized into logical modules:

• core/: Contains the core business logic of the application

  • punch_card.py: The main punch card implementation
  • message_generator.py: Generates messages for the punch card
  • database.py: Handles data persistence

• display/: Handles all visualization and UI elements

  • terminal_display.py: Terminal-based UI implementation
  • gui_display.py: Graphical user interface implementation
  • display_adapter.py: Abstract adapter between core logic and display

• utils/: Utility functions and helpers

  • settings_menu.py: Settings management utilities
  • gui_integration.py: Utilities for GUI functionality

Documentation (docs/)

The docs/ directory contains all project documentation:

• research/: Design research documents including:

  • Interface design history
  • Punch card encoding specifications
  • Early computer design languages

• technical/: Technical documentation including:

  • API specifications
  • Architecture diagrams
  • Implementation details

Testing (tests/)

The tests/ directory contains all test-related files:

• unit/: Unit tests for individual components
• integration/: Tests that verify integration between components
• api/: Tests for external API integrations
• display/: UI and display-specific tests
• legacy/: Older tests kept for reference and historical purposes

Configuration (config/)

The config/ directory contains configuration files:

• templates/: Template configuration files that can be customized

Data Storage (data/)

The data/ directory contains all data files:

• local/: Local data files including:
  • Database files
  • Message templates
  • Sample data

Version Management

The project maintains comprehensive version control through:

• Git versioning: Each version is tagged and has a corresponding branch
• Physical snapshots: Complete archives in the versions/ directory
• Version documentation: Each version has detailed release notes

Git Branching Strategy

The project follows a modified GitFlow branching strategy. For details, see VERSION_CONTROL.md.

Security

API keys and sensitive information are stored in the secrets/ directory, which is excluded from Git. The update_api_key.py script provides a secure way to manage API keys.