Autoparts-DB/docs/plans/2026-02-14-pick-console-design.md

Pick-Style Console System - Design Document

Date: 2026-02-14 Status: Approved

Overview

Console-based autoparts catalog system inspired by Pick/D3 operating systems with VT220 terminal aesthetics. Runs entirely from keyboard in a real terminal (CLI), with two selectable rendering modes: classic VT220 (curses) and modern TUI (textual).

Requirements

• Platform: Real CLI terminal (Python), no web browser
• Users: Sales counter staff AND warehouse/admin personnel
• Style: Pick-inspired with ANSI colors, box drawing, formatted tables
• Data: Abstract DB layer (SQLite today, PostgreSQL migration planned)
• Renderers: Two modes selectable via --mode vt220|modern
• Input: 100% keyboard-driven with F-keys, menus, and incremental search

Architecture

┌─────────────────────────────────────┐
│        Capa de Presentación         │
│  ┌──────────┐    ┌───────────────┐  │
│  │  curses   │    │   textual     │  │
│  │ (VT220)   │    │  (moderno)    │  │
│  └─────┬─────┘    └──────┬────────┘  │
│        └────────┬────────┘           │
│           Interface común            │
├─────────────────────────────────────┤
│      Capa de Lógica / Screens       │
│  Menús, Navegación, Formularios,    │
│  Búsqueda, CRUD                     │
├─────────────────────────────────────┤
│         Capa de Datos (DB)          │
│  SQLite hoy → PostgreSQL mañana     │
└─────────────────────────────────────┘

File Structure

console/
├── main.py                  # Entry point, --mode vt220|modern
├── config.py                # DB path, colors, key mappings
├── db.py                    # Abstract DB layer (SQLite/PostgreSQL)
│
├── core/
│   ├── screens.py           # Screen base class
│   ├── widgets.py           # Lista, Formulario, Tabla, Barra
│   ├── navigation.py        # Screen stack, breadcrumb, history
│   └── keybindings.py       # F-keys, ESC, TAB mappings
│
├── screens/
│   ├── menu_principal.py    # Main menu (9 options + exit)
│   ├── vehiculo_nav.py      # Drill-down: brand → model → year → engine
│   ├── buscar_parte.py      # Search by part number
│   ├── buscar_texto.py      # Full-text search (FTS)
│   ├── vin_decoder.py       # VIN decoder (NHTSA API)
│   ├── catalogo.py          # Categories → groups → parts
│   ├── parte_detalle.py     # Part detail with alternatives
│   ├── comparador.py        # OEM vs aftermarket comparison
│   ├── estadisticas.py      # System statistics dashboard
│   ├── admin_partes.py      # Parts CRUD
│   ├── admin_fabricantes.py # Manufacturers CRUD
│   ├── admin_crossref.py    # Cross-references CRUD
│   └── admin_import.py      # Import/Export CSV
│
├── renderers/
│   ├── curses_renderer.py   # VT220 mode (curses)
│   └── textual_renderer.py  # Modern mode (textual/rich)
│
└── utils/
    ├── formatting.py         # Table formatting, numbers, currency
    └── vin_api.py            # NHTSA VIN API client

Screens

Main Menu

• 9 numbered options + 0 to exit
• F-key bar at bottom
• Header with system name and version

1. Vehicle Navigation (Drill-Down)

• Sequential selection: Brand → Model → Year → Engine
• Each step shows filterable list with incremental search
• Arrow keys + ENTER to select, ESC to go back
• Leads to categories/groups/parts for selected vehicle

2. Part Number Search

• Single input field for part number
• Searches OEM, aftermarket, and cross-references
• Results show type, number, description, source
• Select result to see full detail

3. Text Search (FTS)

• Uses SQLite FTS5 full-text search
• Searches part names and descriptions
• Paginated results with relevance ranking

4. VIN Decoder

• Input 17-character VIN
• Calls NHTSA API (with cache)
• Shows decoded vehicle info
• Option to view compatible parts

5. Category Catalog

• Browse: Categories → Groups → Parts
• Independent of vehicle selection

6-9. Administration

• CRUD screens with Pick-style positional forms
• Numbered fields, TAB/arrow navigation
• F1 for lookup lists on foreign key fields
• F9 to save, ESC to cancel (with dirty check)
• Import/Export CSV with file path input

10. Part Detail

• Full part info in form layout (label.....: value)
• Aftermarket alternatives table below
• F4 for cross-references, F6 for vehicles

11. Part Comparator

• Side-by-side columns: OEM vs aftermarket alternatives
• Visual quality bars, savings percentage
• Cross-reference numbers at bottom
• Horizontal scroll if more than 3 columns

12. Statistics Dashboard

• Database counters (brands, models, parts, etc.)
• Coverage metrics (vehicles with parts, top brands)
• VIN cache status

Key Bindings

Key	Action
0-9	Select menu option / jump to field
ENTER	Confirm selection
ESC	Go back / Cancel
F1	Help / Lookup list
F2	Edit mode
F3	Search
F4	Cross-references
F5	Refresh
F6	Related vehicles
F9	Save
F10	Main menu
TAB / ↓	Next field
↑	Previous field
PgUp/PgDn	Page navigation
←→	Scroll columns (comparator)

Data Layer

Abstract interface with two implementations:

class Database:
    def get_brands() -> list
    def get_models(brand=None) -> list
    def get_vehicles(brand, model, year, engine) -> list
    def get_categories() -> list
    def get_groups(category_id) -> list
    def get_parts(group_id=None, mye_id=None) -> list
    def get_part(part_id) -> dict
    def get_alternatives(part_id) -> list
    def get_cross_references(part_id) -> list
    def search_parts(query) -> list
    def search_part_number(number) -> list
    def decode_vin(vin) -> dict
    def get_stats() -> dict
    # CRUD methods for admin...

SQLite implementation reads directly from vehicle_database.db. PostgreSQL implementation will use psycopg2 with same interface.

Renderer Interface

class Renderer:
    def init_screen()
    def clear()
    def draw_header(title, subtitle)
    def draw_footer(keys)
    def draw_menu(items, selected)
    def draw_table(headers, rows, page_info)
    def draw_form(fields, focused_field)
    def draw_detail(labels_values)
    def draw_comparison(columns)
    def draw_filter_list(items, filter_text, selected)
    def draw_stats(data)
    def get_key() -> key_event
    def show_message(text, type)  # info/error/confirm

Curses implementation uses box drawing chars, ANSI colors (green/amber on black). Textual implementation uses Rich widgets with modern styling.