# zeelladani/digital_clock architecture

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

- Interactive diagram: https://gitdiagram.com/zeelladani/digital_clock
- Repository: https://github.com/zeelladani/digital_clock

## Overview

##### Project Type and Purpose
- This is an embedded electronics project: a standalone digital clock built on an Arduino board.
- The purpose is to read the current time from a DS1307 RTC module, display it on an OLED screen, and optionally trigger an alarm.

##### File Structure Analysis
- Top-level files:
- PROJECT_CLOCK_with_alarm.ino / PROJECT_CLOCK_with_alarm_UPDATED.ino – two versions of the Arduino sketch
- README.md – wiring instructions and library setup
- LICENSE / .gitignore – supporting files
- No separate “src” or “lib” directories because the Arduino IDE expects a single .ino file and associated libraries are installed via the IDE.

##### Key Components (to represent
a. Arduino Uno (or compatible) microcontroller
b. DS1307 Real-Time Clock (RTC) module
c. 128×64 OLED display (SSD1306 driver)
d. Power source (USB or 5 V adapter)
e. (Optional) Buzzer or speaker for alarm output
f. Physical pushbuttons (if used for setting time or alarm)
g. I2C bus (SDA/SCL lines)

##### Relationships and Data Flows
- Power rail (5 V and GND) fans out to Arduino, RTC, OLED, buzzer, buttons.
- I2C bus:
- Arduino A4 (SDA) ↔ RTC SDA & OLED SDA
- Arduino A5 (SCL) ↔ RTC SCL & OLED SCL
- Control flow:
- On startup, Arduino initializes I2C, RTClib, SSD1306.
- Arduino polls RTC for current time.
- Arduino formats time and sends display commands over SPI/I2C to OLED.
- If alarm time reached, Arduino drives buzzer pin HIGH/LOW.
- (If buttons present) Arduino reads digital inputs to set time/alarm.

##### Architectural Patterns and Design Principles
- Layering:
- Hardware layer (power, bus, modules)
- Firmware layer (Arduino sketch: setup() + loop())
- Peripheral libraries (RTClib, Adafruit SSD1306)
- Separation of concerns: timekeeping (RTC), display logic, alarm logic, user input

##### Final Checklist
- Power rails (5 V/GND) drawn consistently
- Callouts for firmware layers or libraries (optional small text)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Power Rails"
        V5[(+5V)]:::vcc
        GND[(GND)]:::gnd
    end

    Arduino[/"Arduino Uno"/]:::microcontroller
    V5 --> Arduino
    GND --> Arduino

    subgraph "I2C Bus (SDA/SCL)"
        SDA["SDA (A4)"]:::bus
        SCL["SCL (A5)"]:::bus
    end
    Arduino --> SDA
    Arduino --> SCL

    RTC(("RTC Module\nDS1307\nRTClib")):::module
    OLED(("OLED Display\nSSD1306")):::module
    SDA --- RTC
    SCL --- RTC
    SDA --- OLED
    SCL --- OLED

    Buzzer(("Buzzer\nPin D2")):::control
    Arduino --> Buzzer
    V5 --> Buzzer
    GND --> Buzzer

    Buttons(("Buttons\nSetting Inputs")):::control
    Arduino --> Buttons
    V5 --> Buttons
    GND --> Buttons

    subgraph "Firmware Layer"
        Sketch1("PROJECT_CLOCK_with_alarm.ino"):::firmware
        Sketch2("PROJECT_CLOCK_with_alarm_UPDATED.ino"):::firmware
    end

    subgraph "Project Files"
        Wiring("Wiring Diagram\n(CONNECTIONS)"):::doc
        Docs("Documentation\n(README.md)"):::doc
        License("License Info\n(LICENSE)"):::doc
        Git("Git Ignore\n(.gitignore)"):::doc
    end

    Docs --> Wiring
    Docs --> License
    Docs --> Git

    click Sketch1 "https://github.com/zeelladani/digital_clock/blob/main/PROJECT_CLOCK_with_alarm.ino"
    click Sketch2 "https://github.com/zeelladani/digital_clock/blob/main/PROJECT_CLOCK_with_alarm_UPDATED.ino"
    click Wiring "https://github.com/zeelladani/digital_clock/tree/main/CONNECTIONS"
    click Docs "https://github.com/zeelladani/digital_clock/blob/main/README.md"
    click License "https://github.com/zeelladani/digital_clock/tree/main/LICENSE"
    click Git "https://github.com/zeelladani/digital_clock/blob/main/.gitignore"

    classDef vcc fill:#ffe5e5,stroke:#ff0000,color:#660000;
    classDef gnd fill:#e0e0e0,stroke:#000000,color:#333333;
    classDef bus stroke:#0000ff,stroke-width:2px,color:#0000ff;
    classDef control stroke:#00aa00,stroke-width:2px,color:#006600;
    classDef microcontroller fill:#e6f2ff,stroke:#003366,color:#003366;
    classDef module fill:#e6ffe6,stroke:#006600,color:#004d00;
    classDef firmware fill:#fff5cc,stroke:#cc9900,color:#665500;
    classDef doc fill:#f9e6ff,stroke:#990099,color:#660066;
```
