# armour/cmpt365 architecture

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

- Interactive diagram: https://gitdiagram.com/armour/cmpt365
- Repository: https://github.com/armour/cmpt365

## Overview

##### Project Type and Purpose
- This is a native iOS application (Xcode, Objective-C + Objective-C++), implementing a JPEG encoder/decoder for educational purposes (CMPT365 assignments).
- Key features: four chroma-subsampling modes, discrete cosine transform (DCT), six quantization tables, end-to-end compression & decompression.

##### High-Level Architecture
- Follows an MVC-style pattern common in iOS apps:
- UI Layer (View Controllers)
- Processing Core (C++ image-processing modules bridged via Objective-C++)
- Data/Model Layer (in-memory image buffers, compressed bitstreams, Core Data model stub)
- Assets & I/O (images from bundle or photo library, saving/displaying results)

##### Main Components
A. User Interface Layer
– ViewController: image selection, initial display
– DCTViewController: visualizing DCT coefficients
– DisplayViewController: showing intermediate stages
– FinalResultViewController: compressed vs. original comparison
B. Processing Core
– MatConvert module: RGB ↔ YCbCr conversion
– Subsampling module: 4:4:4, 4:2:2, 4:2:0, 4:1:1
– DCT module: 8×8 DCT & inverse DCT
– Quantization module: 6 different tables
– (Optional) ZigZag & Bitstream I/O if implemented
C. Data/Model
– UIImage/CGImage buffers
– In-memory block buffers (8×8 coefficient matrices)
– Compressed JPEG byte stream
– Core Data model (present but unused)
D. Assets & I/O
– Bundled sample images
– File system or Photo Library export (if supported)

##### Component Interactions & Data Flow
1. User taps “Load Image” → ViewController → UIImage created
2. Pass UIImage → MatConvert → YCbCr pixel matrix
3. Pixel matrix → Subsampling → downsampled blocks
4. Blocks → DCT module → frequency coefficients
5. Coefficients → Quantization → quantized coefficients
6. (Optional) ZigZag & Huffman packaging → compressed byte stream
7. Byte stream → inverse operations on decompress path
8. FinalResultViewController → renders reconstructed UIImage

##### Architectural Patterns & Principles
- Separation of concerns: UI vs. algorithm core
- Bridging Objective-C++ to isolate C++-only code in .mm files
- MVC pattern: View Controllers orchestrate data flow but delegate heavy work to core modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Context
    XcodeProject["Xcode Project\nJPEG_Compression.xcodeproj"]:::external
    click XcodeProject "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression.xcodeproj"

    %% Application Entry
    subgraph "Application Entry" 
        Main["main.m"]:::external
        AppDelegate["AppDelegate"]:::external
    end
    click Main "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/main.m"
    click AppDelegate "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/AppDelegate.m"

    %% UI Layer
    subgraph "UI Layer" 
        ViewController["ViewController"]:::ui
        ChangeColorVC["ChangeColorViewController"]:::ui
        DCTVC["DCTViewController"]:::ui
        DisplayVC["DisplayViewController"]:::ui
        FinalResultVC["FinalResultViewController"]:::ui
        Storyboards["Storyboards\n(Main & LaunchScreen)"]:::ui
    end
    click ViewController "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/ViewController.mm"
    click ChangeColorVC "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/ChangeColorViewController.mm"
    click DCTVC "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/DCTViewController.mm"
    click DisplayVC "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/DisplayViewController.mm"
    click FinalResultVC "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/FinalResultViewController.mm"
    click Storyboards "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/Base.lproj/Main.storyboard"

    %% Processing Core
    subgraph "Processing Core" 
        MatConvert["MatConvert\n(RGB↔YCbCr)"]:::core
        Subsampling["Subsampling\n(4:4:4,4:2:2,4:2:0,4:1:1)"]:::core
        DCT["DCT & Inverse DCT"]:::core
        Quantization["Quantization\n(6 tables)"]:::core
        BitstreamIO["ZigZag & Bitstream I/O"]:::core
    end
    click MatConvert "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/MatConvert.mm"

    %% Data/Model Layer
    subgraph "Data / Model" 
        UIImageBuf["UIImage / CGImage Buffers"]:::data
        BlockBuf["8×8 Coefficient Block Buffers"]:::data
        ByteStream["Compressed JPEG ByteStream"]:::data
        CoreDataModel["Core Data Model Stub"]:::data
    end
    click CoreDataModel "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/JPEG_Compression.xcdatamodeld"

    %% Assets & I/O
    subgraph "Assets & I/O" 
        AssetsCatalog["Assets.xcassets"]:::assets
        BundledImages["Bundled Sample Images"]:::assets
        PhotoLibrary["Photo Library Export"]:::assets
        FileSystem["File System Export"]:::assets
    end
    click AssetsCatalog "https://github.com/armour/cmpt365/blob/master/JPEG_Compression/JPEG_Compression/Assets.xcassets"
    click BundledImages "https://github.com/armour/cmpt365/tree/master/JPEG_Compression/Images"

    %% Data Flow
    ViewController -->|"UIImage"| MatConvert
    MatConvert -->|"YCbCr Matrix"| Subsampling
    Subsampling -->|"Downsampled Blocks"| DCT
    DCT -->|"Frequency Coefficients"| Quantization
    Quantization -->|"Quantized Coeffs"| BitstreamIO
    BitstreamIO -->|"JPEG ByteStream"| ByteStream
    ByteStream -->|"Decompressed Flow"| Quantization
    Quantization -->|"Inverse Quantization"| DCT
    DCT -->|"Inverse DCT Blocks"| Subsampling
    Subsampling -->|"Upsampled Matrix"| MatConvert
    MatConvert -->|"UIImage"| FinalResultVC

    %% UI Control Flow
    ViewController -->|"select color mode"| ChangeColorVC
    ViewController -->|"view DCT"| DCTVC
    ViewController -->|"view stages"| DisplayVC
    ViewController -->|"show result"| FinalResultVC

    %% Entry Flow
    XcodeProject --> Main --> AppDelegate --> ViewController

    %% Data Artifacts connections
    MatConvert --> UIImageBuf
    Subsampling --> BlockBuf
    BitstreamIO --> ByteStream
    ByteStream --> FinalResultVC

    %% Assets connections
    ViewController -->|loads| BundledImages
    ViewController -->|loads| AssetsCatalog
    FinalResultVC -->|exports| PhotoLibrary
    FinalResultVC -->|exports| FileSystem

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef core fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef data fill:#FFF4B2,stroke:#333,stroke-width:1px
    classDef assets fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
