# andern/pplex architecture

> Architecture diagram of the GitHub repository andern/pplex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andern/pplex
- Repository: https://github.com/andern/pplex

## Overview

1. **What this repo is**
   - `pplex` is a Java-based simplex-method teaching tool for linear programs.
   - It has two front doors: a **desktop app** and an **applet**, both driving the same LP parsing/simulation core.
   - The app is centered on showing how an LP dictionary changes step by step, especially for educational/demo cases.

2. **Top-level runtime split**
   - `src/controller/Main.java` is the main desktop entrypoint.
   - `src/controller/Applet.java` is the browser/applet entrypoint.
   - `src/controller/GUI.java` and `src/controller/Console.java` suggest two interaction modes:
     - a graphical visualization mode,
     - a text-command shell mode (also supported by `-nogui` per README).

3. **Core domain model**
   - `src/model/LP.java` is the main in-memory representation of a linear program/dictionary.
   - This is the central state object that all commands operate on.
   - The design implies a mostly stateful flow: parse LP → store in `LP` → mutate via simplex commands → render current state.

4. **Input parsing boundary**
   - LP files are read from the `input/` examples and user-supplied `.lps` files.
   - `src/parser/LpFileFormat.g` is an ANTLR grammar, so file parsing is generated from a formal LP language definition.
   - This separates **file syntax** from the simplex engine: parsing produces model state, but the simplex logic does not appear to live in the parser.

5. **Command-driven simplex engine**
   - `src/controller/shellcommands/` contains the operational commands exposed in the console:
     - `Read`, `Phase1`, `Phase2`, `Pivot`, `Undo`, `Redo`
     - inspection commands like `Show`, `ShowDual`, `ShowFeas`, `ShowOpt`, `ShowPrimal`
     - utility/meta commands like `FormatCmd`, `Conditions`, `Warranty`, `Exit`
   - These are the main mutation and inspection boundary around the LP state.
   - The architecture is essentially a command dispatcher over a shared LP/session object.

6. **Dual representation: computation vs presentation**
   - `src/output/Output.java`, `OLP.java`, and `OMatrix.java` indicate a formatting layer that converts LP/matrix state into user-visible text or structured output.
   - This layer is separate from the model, so the app can present the same LP state in multiple forms:
     - primal/dual views,
     - feasibility/optimality views,
     - matrix/dictionary views.
   - That boundary matters for the diagram: the model is not rendered directly; it is adapted through output classes.

7. **Visualization subsystem**
   - The README emphasizes graphical visualization of the simplex dictionary evolution.
   - `src/controller/VisLP.java` likely bridges LP state into a visual form usable by the GUI.
   - `src/controller/Screenshot.java` suggests the GUI can export the current visualization.
   - The GUI is likely limited to small-dimensional LPs, consistent with the README note that visual mode is only relevant for two-variable problems.

8. **Application flow**
   - Typical flow is:
     - user loads an `.lps` file with `Read`
     - parser builds an `LP`
     - user runs `Phase1`, `Phase2`, or `Pivot`
     - command updates LP state
     - GUI/console output reflects the current dictionary, feasibility, or optimality status
   - Undo/redo indicate the app keeps a history of prior simplex states or command states.

9. **Supporting assets and examples**
   - `input/` contains many sample LPs demonstrating edge cases: cycling, degeneracy, dual-feasible cases, unboundedness, sensitivity, etc.
   - `doc/teaching_simplex/` contains matching explanatory material and example instances used for instruction.
   - These are not runtime subsystems, but they show the app is designed for pedagogy and regression testing of simplex behavior.

10. **External libraries and tooling that affect architecture**
   - Apache Commons Math is used for matrix handling, so the LP/matrix math is not hand-rolled.
   - ANTLR is used for parsing.
   - `lightshell.jar` suggests the console shell is built on a shell framework.
   - Build is Ant-based (`build.xml`), producing `pplex.jar` and an applet target.

11. **Deployment/runtime environment**
   - The app is a pure Java application requiring a JRE/JDK depending on whether it is run or built.
   - It supports:
     - direct jar execution,
     - terminal/no-GUI mode,
     - applet deployment via `applet.html`.
   - That makes the architecture portable but still centered on a single JVM codebase.

12. **Key architectural boundaries to show in a diagram**
   - **UI boundary:** console/GUI/applet entrypoints.
   - **Parsing boundary:** `.lps` text → ANTLR grammar → LP model.
   - **Computation boundary:** simplex commands mutate LP state.
   - **Presentation boundary:** output/visualization adapters render the current state.
   - **State/history boundary:** undo/redo and phase transitions manage progression through simplex execution.

Main entry points: [`src/controller/Console.java`](https://github.com/andern/pplex/blob/master/src/controller/Console.java) (Console), [`src/controller/Data.java`](https://github.com/andern/pplex/blob/master/src/controller/Data.java) (Data), [`src/model/LP.java`](https://github.com/andern/pplex/blob/master/src/model/LP.java) (LP), [`src/output/OLP.java`](https://github.com/andern/pplex/blob/master/src/output/OLP.java) (OLP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime entrypoints"]
  node_main["Main<br/>desktop entrypoint<br/>[Main.java]"]
  node_applet["Applet<br/>[Applet.java]"]
  node_console["Console<br/>shell UI<br/>[Console.java]"]
  node_gui["GUI<br/>visual UI<br/>[GUI.java]"]
  node_data[("Data<br/>[Data.java]")]
end

subgraph group_commands["Command engine"]
  node_read["Read<br/>load command<br/>[Read.java]"]
  node_phase1["Phase1<br/>simplex command<br/>[Phase1.java]"]
  node_phase2["Phase2<br/>simplex command<br/>[Phase2.java]"]
  node_pivot["Pivot<br/>[Pivot.java]"]
  node_undo["Undo<br/>history command<br/>[Undo.java]"]
  node_redo["Redo<br/>history command<br/>[Redo.java]"]
  node_show["Show<br/>inspect command<br/>[Show.java]"]
  node_showdual["ShowDual<br/>inspect command<br/>[ShowDual.java]"]
  node_showfeas["ShowFeas<br/>inspect command<br/>[ShowFeas.java]"]
  node_showopt["ShowOpt<br/>inspect command<br/>[ShowOpt.java]"]
  node_showprimal["ShowPrimal<br/>inspect command<br/>[ShowPrimal.java]"]
end

subgraph group_core["Core LP"]
  node_lp[("LP<br/>state model<br/>[LP.java]")]
  node_grammar["Lp Grammar<br/>ANTLR grammar<br/>[LpFileFormat.g]"]
end

subgraph group_presentation["Presentation"]
  node_output["Output<br/>format adapter<br/>[Output.java]"]
  node_olp["OLP<br/>LP formatter<br/>[OLP.java]"]
  node_omatrix["OMatrix<br/>matrix formatter<br/>[OMatrix.java]"]
  node_vislp["VisLP<br/>visual adapter<br/>[VisLP.java]"]
  node_screenshot["Screenshot<br/>export utility<br/>[Screenshot.java]"]
end

node_main -->|"launches"| node_console
node_main -->|"launches"| node_gui
node_applet -->|"hosts"| node_gui
node_console -->|"dispatches"| node_read
node_console -->|"dispatches"| node_phase1
node_console -->|"dispatches"| node_phase2
node_console -->|"dispatches"| node_pivot
node_console -->|"dispatches"| node_undo
node_console -->|"dispatches"| node_redo
node_console -->|"dispatches"| node_show
node_console -->|"dispatches"| node_showdual
node_console -->|"dispatches"| node_showfeas
node_console -->|"dispatches"| node_showopt
node_console -->|"dispatches"| node_showprimal
node_read -->|"parses with"| node_grammar
node_read -->|"loads into"| node_lp
node_phase1 -->|"mutates"| node_lp
node_phase2 -->|"mutates"| node_lp
node_pivot -->|"mutates"| node_lp
node_undo -->|"rewinds"| node_data
node_redo -->|"replays"| node_data
node_show -->|"formats via"| node_output
node_showdual -->|"formats via"| node_olp
node_showfeas -->|"formats via"| node_olp
node_showopt -->|"formats via"| node_olp
node_showprimal -->|"formats via"| node_olp
node_output -->|"specializes to"| node_olp
node_output -->|"specializes to"| node_omatrix
node_gui -->|"renders with"| node_vislp
node_vislp -->|"reads"| node_lp
node_screenshot -->|"captures"| node_gui
node_read -->|"updates context"| node_data
node_phase1 -->|"updates context"| node_data
node_phase2 -->|"updates context"| node_data
node_pivot -->|"updates context"| node_data

click node_main "https://github.com/andern/pplex/blob/master/src/controller/Main.java"
click node_applet "https://github.com/andern/pplex/blob/master/src/controller/Applet.java"
click node_console "https://github.com/andern/pplex/blob/master/src/controller/Console.java"
click node_gui "https://github.com/andern/pplex/blob/master/src/controller/GUI.java"
click node_read "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Read.java"
click node_phase1 "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Phase1.java"
click node_phase2 "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Phase2.java"
click node_pivot "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Pivot.java"
click node_undo "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Undo.java"
click node_redo "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Redo.java"
click node_show "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Show.java"
click node_showdual "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowDual.java"
click node_showfeas "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowFeas.java"
click node_showopt "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowOpt.java"
click node_showprimal "https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowPrimal.java"
click node_lp "https://github.com/andern/pplex/blob/master/src/model/LP.java"
click node_grammar "https://github.com/andern/pplex/blob/master/src/parser/LpFileFormat.g"
click node_output "https://github.com/andern/pplex/blob/master/src/output/Output.java"
click node_olp "https://github.com/andern/pplex/blob/master/src/output/OLP.java"
click node_omatrix "https://github.com/andern/pplex/blob/master/src/output/OMatrix.java"
click node_vislp "https://github.com/andern/pplex/blob/master/src/controller/VisLP.java"
click node_screenshot "https://github.com/andern/pplex/blob/master/src/controller/Screenshot.java"
click node_data "https://github.com/andern/pplex/blob/master/src/controller/Data.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_applet,node_console,node_gui,node_data toneBlue
class node_read,node_phase1,node_phase2,node_pivot,node_undo,node_redo,node_show,node_showdual,node_showfeas,node_showopt,node_showprimal toneAmber
class node_lp,node_grammar toneMint
class node_output,node_olp,node_omatrix,node_vislp,node_screenshot toneRose
```

## Components

### Runtime entrypoints

Desktop, applet, and shell front doors

- [Main](https://github.com/andern/pplex/blob/master/src/controller/Main.java): desktop entrypoint · Starts the desktop application · `src/controller/Main.java`
- [Applet](https://github.com/andern/pplex/blob/master/src/controller/Applet.java): applet entrypoint · Browser/applet launcher · `src/controller/Applet.java`
- [Console](https://github.com/andern/pplex/blob/master/src/controller/Console.java): shell UI · Text-command interface for simplex operations · `src/controller/Console.java`
- [GUI](https://github.com/andern/pplex/blob/master/src/controller/GUI.java): visual UI · Graphical interface for dictionary evolution · `src/controller/GUI.java`
- [Data](https://github.com/andern/pplex/blob/master/src/controller/Data.java): shared session data · Application-wide state and command context · `src/controller/Data.java`

### Command engine

Console commands that mutate or inspect simplex state

- [Read](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Read.java): load command · Loads LP input from file · `src/controller/shellcommands/Read.java`
- [Phase1](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Phase1.java): simplex command · Runs phase I feasibility search · `src/controller/shellcommands/Phase1.java`
- [Phase2](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Phase2.java): simplex command · Runs phase II optimization · `src/controller/shellcommands/Phase2.java`
- [Pivot](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Pivot.java): pivot command · Performs one simplex pivot step · `src/controller/shellcommands/Pivot.java`
- [Undo](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Undo.java): history command · Reverts to a prior state · `src/controller/shellcommands/Undo.java`
- [Redo](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Redo.java): history command · Restores an undone state · `src/controller/shellcommands/Redo.java`
- [Show](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/Show.java): inspect command · Displays the current LP state · `src/controller/shellcommands/Show.java`
- [ShowDual](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowDual.java): inspect command · Displays the dual form · `src/controller/shellcommands/ShowDual.java`
- [ShowFeas](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowFeas.java): inspect command · Displays feasibility status · `src/controller/shellcommands/ShowFeas.java`
- [ShowOpt](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowOpt.java): inspect command · Displays optimality status · `src/controller/shellcommands/ShowOpt.java`
- [ShowPrimal](https://github.com/andern/pplex/blob/master/src/controller/shellcommands/ShowPrimal.java): inspect command · Displays the primal form · `src/controller/shellcommands/ShowPrimal.java`

### Core LP

In-memory linear-program state and parsing boundary

- [LP](https://github.com/andern/pplex/blob/master/src/model/LP.java): state model · Mutable linear-program dictionary and session state · `src/model/LP.java`
- [Lp Grammar](https://github.com/andern/pplex/blob/master/src/parser/LpFileFormat.g): ANTLR grammar · Formal syntax for .lps input files · `src/parser/LpFileFormat.g`

### Presentation

Text and visual rendering adapters

- [Output](https://github.com/andern/pplex/blob/master/src/output/Output.java): format adapter · Shared output formatting base · `src/output/Output.java`
- [OLP](https://github.com/andern/pplex/blob/master/src/output/OLP.java): LP formatter · Formats LP and dictionary views · `src/output/OLP.java`
- [OMatrix](https://github.com/andern/pplex/blob/master/src/output/OMatrix.java): matrix formatter · Formats matrix-style views · `src/output/OMatrix.java`
- [VisLP](https://github.com/andern/pplex/blob/master/src/controller/VisLP.java): visual adapter · Bridges LP state into GUI-friendly visualization · `src/controller/VisLP.java`
- [Screenshot](https://github.com/andern/pplex/blob/master/src/controller/Screenshot.java): export utility · Captures the current visualization · `src/controller/Screenshot.java`

## Connections

- Main → Console: launches · Desktop entrypoint can start the shell mode
- Main → GUI: launches · Desktop entrypoint can start the graphical mode
- Applet → GUI: hosts · Applet entrypoint drives the visual UI
- Console → Read: dispatches · Shell routes user commands to operations
- Console → Phase1: dispatches · Shell routes user commands to operations
- Console → Phase2: dispatches · Shell routes user commands to operations
- Console → Pivot: dispatches · Shell routes user commands to operations
- Console → Undo: dispatches · Shell routes user commands to operations
- Console → Redo: dispatches · Shell routes user commands to operations
- Console → Show: dispatches · Shell routes user commands to operations
- Console → ShowDual: dispatches · Shell routes user commands to operations
- Console → ShowFeas: dispatches · Shell routes user commands to operations
- Console → ShowOpt: dispatches · Shell routes user commands to operations
- Console → ShowPrimal: dispatches · Shell routes user commands to operations
- Read → Lp Grammar: parses with · LP files are defined by the ANTLR grammar
- Read → LP: loads into · Parsed LP input becomes session state
- Phase1 → LP: mutates · Phase I updates feasibility-related LP state
- Phase2 → LP: mutates · Phase II updates optimization state
- Pivot → LP: mutates · Pivot step rewrites the current dictionary
- Undo → Data: rewinds · History is managed through shared session data
- Redo → Data: replays · History is managed through shared session data
- Show → Output: formats via · Inspection commands render through the output layer
- ShowDual → OLP: formats via · Dual view uses LP formatting
- ShowFeas → OLP: formats via · Feasibility view uses LP formatting
- ShowOpt → OLP: formats via · Optimality view uses LP formatting
- ShowPrimal → OLP: formats via · Primal view uses LP formatting
- Output → OLP: specializes to · LP-specific formatter builds on shared output support
- Output → OMatrix: specializes to · Matrix formatter builds on shared output support
- GUI → VisLP: renders with · GUI uses the visualization adapter for LP state
- VisLP → LP: reads · Visualization is derived from the current LP dictionary
- Screenshot → GUI: captures · Screenshot utility exports the visible GUI state
- Read → Data: updates context · Loaded files update shared application context
- Phase1 → Data: updates context · Command execution updates shared application context
- Phase2 → Data: updates context · Command execution updates shared application context
- Pivot → Data: updates context · Command execution updates shared application context