# frozsgy/ceng336-hw architecture

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

- Interactive diagram: https://gitdiagram.com/frozsgy/ceng336-hw
- Repository: https://github.com/frozsgy/ceng336-hw

## Overview

##### Project type and purpose
- This repository is not a web app or microservice suite but a collection of embedded‐systems coursework and a supporting utility.
- It contains three “Take Home Exam” modules (THE1 and THE2 in PIC18F8722 assembly, THE3 in C) plus a Python-based “Timer Calculator” for computing PIC18F8722 timer register values.

##### File structure
- Top level: LICENSE, README.md, three exam folders (THE1, THE2, THE3) and one tool folder (“Timer Calculator”).
- THE1 & THE2 each contain an .asm source and PDF spec; THE3 has main.c and PDF spec.
- “Timer Calculator” holds a README, main.py (CLI entrypoint) and timer.py (core logic).

##### Mine the README for technical stack
- All embedded code targets the PIC18F8722 microcontroller, developed in MPLABX.
- Assembly assignments (interrupts, timers), C assignment (number-guessing game with timers/interrupts).
- The Python tool runs on the host to pre-compute timer values for the same PIC.

##### Main components
a. Exam Modules
- THE1 Module (MPLABX + PIC18F8722 assembler)
- THE2 Module (MPLABX + PIC18F8722 assembler with interrupts/timers)
- THE3 Module (MPLABX + PIC18F8722 in C with RTOS-style constructs)
b. Timer Calculator Tool
- CLI layer (main.py)
- Core logic layer (timer.py)
- Output (recommended register settings)
c. External/Supporting Components
- MPLABX IDE & XC-Compiler toolchain
- PIC18F8722 hardware (or simulator)

##### Relationships and interactions
- Each THEx folder → assembled/compiled by MPLABX → loaded onto PIC18F8722 → exercises specific peripherals (timers, interrupts, I/O).
- Timer Calculator: user invokes main.py → calls timer.py to compute register values → user copies results into MPLABX projects.

##### Architectural patterns & design principles
- Separation by assignment: each exam is a self-contained component.
- In the Python tool: clear layering of CLI vs. business logic.
- Consistent use of per-module README + PDF spec for documentation.

##### Recommended elements
- Component names (THE1, THE2, THE3, Timer Calculator CLI, Timer Logic)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External User
  User["User/Terminal"]:::user

  %% Embedded Assignments Group
  subgraph "Embedded Assignments"
    direction TB
    subgraph THE1["THE1 Module"]
      direction TB
      THE1_src["the1.asm"]:::exam
      THE1_spec["THE1.pdf"]:::exam
    end
    subgraph THE2["THE2 Module"]
      direction TB
      THE2_src["the2.asm"]:::exam
      THE2_spec1["the2.pdf"]:::exam
      THE2_spec2["the2_v2.pdf"]:::exam
    end
    subgraph THE3["THE3 Module"]
      direction TB
      THE3_src["main.c"]:::exam
      THE3_spec["the3_336_20192.pdf"]:::exam
    end
  end

  %% Host Utility Group
  subgraph "Host Utility"
    direction TB
    subgraph "Timer Calculator"
      direction TB
      README["README.md"]:::cli
      CLI["main.py"]:::cli
      Core["timer.py"]:::core
    end
  end

  %% Toolchain and Hardware
  MPLABX["MPLABX IDE\nXC-Compiler"]:::toolchain
  PIC[(PIC18F8722 Hardware/Simulator)]:::hardware

  %% Build & Deploy Flows
  THE1_src -->|"assemble/build"| MPLABX
  THE2_src -->|"assemble/build"| MPLABX
  THE3_src -->|"compile/build"| MPLABX
  MPLABX -->|"flash/deploy"| PIC

  %% Timer Calculator Flows
  User -->|"invoke compute registers"| CLI
  CLI -->|"compute registers"| Core
  Core -->|"output settings"| User

  %% Click Events
  click THE1_src "https://github.com/frozsgy/ceng336-hw/blob/main/THE1/the1.asm"
  click THE1_spec "https://github.com/frozsgy/ceng336-hw/blob/main/THE1/THE1.pdf"
  click THE2_src "https://github.com/frozsgy/ceng336-hw/blob/main/THE2/the2.asm"
  click THE2_spec1 "https://github.com/frozsgy/ceng336-hw/blob/main/THE2/the2.pdf"
  click THE2_spec2 "https://github.com/frozsgy/ceng336-hw/blob/main/THE2/the2_v2.pdf"
  click THE3_src "https://github.com/frozsgy/ceng336-hw/blob/main/THE3/main.c"
  click THE3_spec "https://github.com/frozsgy/ceng336-hw/blob/main/THE3/the3_336_20192.pdf"
  click CLI "https://github.com/frozsgy/ceng336-hw/blob/main/Timer Calculator/main.py"
  click Core "https://github.com/frozsgy/ceng336-hw/blob/main/Timer Calculator/timer.py"
  click README "https://github.com/frozsgy/ceng336-hw/blob/main/Timer Calculator/README.md"

  %% Styles
  classDef exam fill:#cce5ff,stroke:#339,stroke-width:1px;
  classDef cli fill:#d4edda,stroke:#2a9d31,stroke-width:1px;
  classDef core fill:#d4edda,stroke:#2a9d31,stroke-width:1px;
  classDef toolchain fill:#fff3cd,stroke:#cca800,stroke-width:1px,stroke-dasharray: 5 5;
  classDef hardware fill:#e2e3e5,stroke:#6c757d,stroke-width:1px,stroke-dasharray: 2 2;
  classDef user fill:#f8d7da,stroke:#842029,stroke-width:1px;
```
