# cirocosta/observer-c architecture

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

- Interactive diagram: https://gitdiagram.com/cirocosta/observer-c
- Repository: https://github.com/cirocosta/observer-c

## Overview

#### Purpose and Entry Points
`observer-c` is a small pure-C implementation of the Observer pattern. It provides reusable subject/observer interfaces, demonstrated by an animal-event program. Primary consumer entry points are `observer/observer.h` and `observer/subject.h`; the runnable example begins at `example/main.c`.

#### Observer Contract
Observers implement a notification callback defined by the observer abstraction. Subject implementations hold observer registrations and invoke that callback when their domain event occurs.
- `observer/observer.h`
- `observer/observer.c`
- `observer/common.h`

This is a callback/function-pointer design: observers depend only on the observer contract, rather than concrete subject types.

#### Subject Lifecycle and Registration
The subject layer defines the observable-side interface and owns registration/removal behavior. A concrete subject must implement its subject interface plus `registerObserver` and `unregisterObserver`, establishing the lifecycle boundary between a publisher and its listeners.
- `observer/subject.h`
- `observer/subject.c`
- `observer/common.h`

#### Notification Flow
Control flows from application code into a concrete subject event, then through the subject’s registered observer set, and finally into each observer’s `notify` implementation. Notification is synchronous and in-process; there is no broker, persistence, network transport, or asynchronous runtime indicated by the repository.
- `observer/subject.c`
- `observer/observer.c`
- `example/models/cat.c`

#### Concrete Domain Example
The example models a cat as the subject whose meow triggers reactions from animal observers. Cat-specific code adapts the generic subject mechanism to the event, while dog code implements a distinct observer reaction.
- `example/models/cat.h`
- `example/models/cat.c`
- `example/models/dog.c`

#### Application Composition
The example executable constructs the participating animal objects, connects observers to the cat, and triggers the observed behavior. It is the integration point that demonstrates object initialization, registration, event emission, and callback dispatch.
- `example/main.c`
- `example/function-pointer.c`

#### Runtime and Verification
The project targets a native C toolchain, with build/test orchestration centered on `Makefile`. There are no external services or infrastructure dependencies. Behavioral validation focuses on observable registration and notification semantics.
- `Makefile`
- `tests/test-observable.c`

Main entry points: [`observer/observer.h`](https://github.com/cirocosta/observer-c/blob/master/observer/observer.h) (Observer contract), [`example/main.c`](https://github.com/cirocosta/observer-c/blob/master/example/main.c) (Example executable), [`observer/subject.c`](https://github.com/cirocosta/observer-c/blob/master/observer/subject.c) (Subject registration), [`example/models/cat.c`](https://github.com/cirocosta/observer-c/blob/master/example/models/cat.c) (Cat meow event)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Observer Library"]
  node_observer_contract["Observer contract<br/>C interface<br/>[observer.h]"]
  node_observer_impl["Observer implementation<br/>C implementation<br/>[observer.c]"]
  node_subject_contract["Subject contract<br/>C interface<br/>[subject.h]"]
  node_subject_impl["Subject registration<br/>C implementation<br/>[subject.c]"]
  node_common_types["Shared types<br/>C header<br/>[common.h]"]
end

subgraph group_example["Animal Example"]
  node_cat_api["Cat subject API<br/>C interface<br/>[cat.h]"]
  node_cat_subject["Cat meow event<br/>concrete subject<br/>[cat.c]"]
  node_dog_observer["Dog reaction<br/>concrete observer<br/>[dog.c]"]
  node_example_main{{"Example executable<br/>application entry<br/>[main.c]"}}
  node_function_pointer_demo["Function pointer demo<br/>example program<br/>[function-pointer.c]"]
end

subgraph group_runtime["Build &amp; Runtime"]
  node_makefile["Make orchestration<br/>build system"]
  node_native_runtime(("Native C runtime<br/>in-process runtime"))
end

node_observer_contract -->|"implemented by"| node_observer_impl
node_subject_contract -->|"implemented by"| node_subject_impl
node_common_types -->|"shared definitions"| node_observer_contract
node_common_types -->|"shared definitions"| node_subject_contract
node_observer_contract -->|"callback contract"| node_subject_impl
node_cat_api -->|"declares"| node_cat_subject
node_subject_contract -->|"implements"| node_cat_subject
node_observer_contract -->|"implements notify"| node_dog_observer
node_example_main -->|"creates and triggers"| node_cat_subject
node_example_main -->|"creates and registers"| node_dog_observer
node_cat_subject -->|"uses registration and dispatch"| node_subject_impl
node_subject_impl -->|"synchronous notify"| node_dog_observer
node_makefile -->|"builds"| node_example_main
node_makefile -->|"builds"| node_function_pointer_demo
node_example_main -->|"runs in"| node_native_runtime
node_function_pointer_demo -->|"runs in"| node_native_runtime

click node_observer_contract "https://github.com/cirocosta/observer-c/blob/master/observer/observer.h"
click node_observer_impl "https://github.com/cirocosta/observer-c/blob/master/observer/observer.c"
click node_subject_contract "https://github.com/cirocosta/observer-c/blob/master/observer/subject.h"
click node_subject_impl "https://github.com/cirocosta/observer-c/blob/master/observer/subject.c"
click node_common_types "https://github.com/cirocosta/observer-c/blob/master/observer/common.h"
click node_cat_api "https://github.com/cirocosta/observer-c/blob/master/example/models/cat.h"
click node_cat_subject "https://github.com/cirocosta/observer-c/blob/master/example/models/cat.c"
click node_dog_observer "https://github.com/cirocosta/observer-c/blob/master/example/models/dog.c"
click node_example_main "https://github.com/cirocosta/observer-c/blob/master/example/main.c"
click node_function_pointer_demo "https://github.com/cirocosta/observer-c/blob/master/example/function-pointer.c"
click node_makefile "https://github.com/cirocosta/observer-c/blob/master/Makefile"

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_observer_contract,node_observer_impl,node_subject_contract,node_subject_impl,node_common_types toneBlue
class node_cat_api,node_cat_subject,node_dog_observer,node_example_main,node_function_pointer_demo toneAmber
class node_makefile,node_native_runtime toneMint
```

## Components

### Observer Library

Reusable callback-based observer and subject contracts.

- [Observer contract](https://github.com/cirocosta/observer-c/blob/master/observer/observer.h): C interface · Defines the notification callback abstraction. · `observer/observer.h`
- [Observer implementation](https://github.com/cirocosta/observer-c/blob/master/observer/observer.c): C implementation · `observer/observer.c`
- [Subject contract](https://github.com/cirocosta/observer-c/blob/master/observer/subject.h): C interface · Defines observable-side registration and removal. · `observer/subject.h`
- [Subject registration](https://github.com/cirocosta/observer-c/blob/master/observer/subject.c): C implementation · Owns registered observers and synchronous dispatch. · `observer/subject.c`
- [Shared types](https://github.com/cirocosta/observer-c/blob/master/observer/common.h): C header · `observer/common.h`

### Animal Example

Concrete cat event and dog observer composition.

- [Cat subject API](https://github.com/cirocosta/observer-c/blob/master/example/models/cat.h): C interface · `example/models/cat.h`
- [Cat meow event](https://github.com/cirocosta/observer-c/blob/master/example/models/cat.c): concrete subject · Adapts a meow into generic subject notification. · `example/models/cat.c`
- [Dog reaction](https://github.com/cirocosta/observer-c/blob/master/example/models/dog.c): concrete observer · Implements a distinct notify callback reaction. · `example/models/dog.c`
- [Example executable](https://github.com/cirocosta/observer-c/blob/master/example/main.c): application entry · Constructs animals, registers observers, and triggers the cat event. · `example/main.c`
- [Function pointer demo](https://github.com/cirocosta/observer-c/blob/master/example/function-pointer.c): example program · `example/function-pointer.c`

### Build & Runtime

- [Make orchestration](https://github.com/cirocosta/observer-c/blob/master/Makefile): build system · Builds and runs native C targets. · `Makefile`
- **Native C runtime**: in-process runtime · Synchronous callback execution with no external transport.

## Connections

- Observer contract → Observer implementation: implemented by
- Subject contract → Subject registration: implemented by
- Shared types → Observer contract: shared definitions
- Shared types → Subject contract: shared definitions
- Observer contract → Subject registration: callback contract
- Cat subject API → Cat meow event: declares
- Subject contract → Cat meow event: implements
- Observer contract → Dog reaction: implements notify
- Example executable → Cat meow event: creates and triggers
- Example executable → Dog reaction: creates and registers
- Cat meow event → Subject registration: uses registration and dispatch
- Subject registration → Dog reaction: synchronous notify · Dispatches to each registered observer.
- Make orchestration → Example executable: builds
- Make orchestration → Function pointer demo: builds
- Example executable → Native C runtime: runs in
- Function pointer demo → Native C runtime: runs in