Punch Card Project: System Architecture

This page provides comprehensive diagrams and explanations of the Punch Card Project's architecture.

Overall System Architecture

┌───────────────────────────────────────────────────────────────────────────┐
│                            Punch Card Project                              │
└───────────────────────────────────────────────────────────────────────────┘
                                    │
                 ┌─────────────────┬┴┬─────────────────┐
                 │                 │  │                 │
       ┌─────────▼─────────┐      │  │      ┌──────────▼───────────┐
       │       GUI         │      │  │      │    Terminal Mode     │
       │   Interface       │      │  │      │    Interface         │
       └─────────┬─────────┘      │  │      └──────────┬───────────┘
                 │                │  │                 │
                 │         ┌──────▼──▼───────┐         │
                 │         │                 │         │
                 └────────►│   Core Engine   │◄────────┘
                           │                 │
                           └────────┬────────┘
                                    │
            ┌────────────┬──────────┼──────────┬────────────┐
            │            │          │          │            │
   ┌────────▼─────┐     ┌▼────────────┐     ┌──▼────┐     ┌─▼──────────┐
   │  LED State   │     │ Punch Card  │     │ API   │     │ Hardware   │
   │  Manager     │     │ Encoder     │     │ Client│     │ Controller │
   └──────────────┘     └─────────────┘     └───────┘     └────────────┘
                                                                │
                                                         ┌──────┴───────┐
                                                         │ Physical or  │
                                                         │ Simulated    │
                                                         │ Hardware     │
                                                         └──────────────┘

Component Interactions

UI Components

The Punch Card Project offers two primary user interfaces:

1. GUI Interface - Interactive graphical interface with:

   • Punch card visualization
   • Input options and controls
   • Status display and feedback
   • Interactive card editing

2. Terminal Interface - Text-based interface with:

   • ASCII representation of punch cards
   • Command-line options
   • Test modes and diagnostics
   • Hardware integration tools

Both interfaces communicate with the Core Engine, which manages all project functionality.

Core Components

1. Core Engine

   • Central coordinator of the system
   • Manages application state
   • Routes commands between components
   • Handles configuration settings
   • Manages error handling and logging

2. LED State Manager

   • Maintains the state of all LEDs in memory
   • Provides APIs for manipulating LED states
   • Handles transitions and animations
   • Ensures consistent state representation

3. Punch Card Encoder

   • Converts text to punch card patterns
   • Implements IBM 026, IBM 029, and UNIVAC encoding standards
   • Handles character validation
   • Manages encoding/decoding operations

4. API Client

   • Communicates with external APIs (OpenAI)
   • Handles authentication and key management
   • Manages rate limiting and error recovery
   • Processes API responses

5. Hardware Controller

   • Abstracts physical hardware details
   • Supports Raspberry Pi GPIO for physical LEDs
   • Provides simulation mode for testing
   • Handles hardware initialization and shutdown

Data Flow

┌─────────────┐    ┌───────────┐    ┌──────────────┐    ┌─────────────┐
│  User Input  │───►│ Interface │───►│ Core Engine  │───►│  Encoder    │
└─────────────┘    └───────────┘    └──────────────┘    └──────┬──────┘
                                                               │
                                                               ▼
┌─────────────┐    ┌───────────┐    ┌──────────────┐    ┌─────────────┐
│  Output     │◄───│ Hardware  │◄───│ LED Manager  │◄───│  Card Data  │
└─────────────┘    └───────────┘    └──────────────┘    └─────────────┘

1. Input Processing Flow:

   • User provides input via GUI or Terminal
   • Interface passes commands to Core Engine
   • Core Engine validates and processes input
   • Input is encoded into punch card patterns
   • LED states are updated based on patterns
   • Hardware controller updates physical or simulated hardware

2. External API Flow:

   • Core Engine requests external data (if needed)
   • API Client handles authentication and requests
   • Response is processed by Core Engine
   • Results are encoded and displayed

Module Structure

The codebase is organized into logical modules:

src/
├── core/               # Core functionality
│   ├── engine.py       # Central coordination
│   ├── config.py       # Configuration management
│   └── utils.py        # Core utilities
├── display/            # Display components
│   ├── gui/            # GUI interface
│   │   ├── main_window.py
│   │   ├── widgets.py
│   │   └── controllers.py
│   └── terminal/       # Terminal interface
│       ├── ui.py
│       ├── console.py
│       └── formatters.py
├── hardware/           # Hardware abstraction
│   ├── controller.py   # Hardware controller base
│   ├── led_manager.py  # LED state management
│   ├── simulator.py    # Hardware simulation
│   └── rpi.py          # Raspberry Pi implementation
├── encoding/           # Card encoding
│   ├── ibm026.py       # IBM 026 encoding
│   ├── ibm029.py       # IBM 029 encoding
│   ├── univac.py       # UNIVAC encoding
│   └── custom.py       # Custom encoding support
└── api/                # External API integration
    ├── client.py       # API client base
    ├── openai.py       # OpenAI integration
    └── key_manager.py  # API key management

Testing Architecture

The project includes a comprehensive testing infrastructure:

tests/
├── unit/              # Unit tests
│   ├── core/          # Core component tests
│   ├── display/       # Display component tests
│   ├── hardware/      # Hardware component tests
│   └── encoding/      # Encoding component tests
├── integration/       # Integration tests
│   ├── gui_tests.py   # GUI integration
│   ├── terminal_tests.py # Terminal integration
│   └── api_tests.py   # API integration
└── e2e/               # End-to-end tests
    ├── scenarios/     # Test scenarios
    └── fixtures/      # Test data

Configuration Management

Configuration is managed through a hierarchical system:

1. Command Line Arguments - Highest priority
2. Environment Variables - Second priority
3. Configuration Files - Third priority
4. Default Settings - Lowest priority

---

This architecture document will be updated as the system evolves.