# hadichahine/cest architecture

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

- Interactive diagram: https://gitdiagram.com/hadichahine/cest
- Repository: https://github.com/hadichahine/cest

## Overview

##### Project Type and Purpose
- This is an open-source C library (“cest”) that provides a minimal unit-testing framework for GNU/Linux environments.
- It exposes two APIs: a low-level “inner” API (CUTest/CUTestSuite) and a higher-level test suite constructor. It links against libc and bundles a static dependency (exceptions4c).

##### High-Level Components
a. Core Library
- src/*.c (cutest.c, cutestsuite.c, cutest_assert.c, linkedlist.c, mem_alloc.c)
- headers/*.h (public API: cutest.h, cutestsuite.h, create_test_suite.h, linkedlist.h, mem_alloc.h, cupcet_assert.h)
b. Static Dependency
- static_dependencies/exceptions4c (e4c.c, e4c.h) – exception handling layer
c. Primitive Testing Harness
- primitive_testing/primitive_testing_environment.c/.h – basic internal tests & scaffolding
d. User Tests
- tests/*.c – test cases that exercise the core library
e. Build & CI
- Makefile – build targets: all, check, install, test-debug
- .travis.yml – continuous integration commands
f. Deployment Packaging
- deployment/archlinux/cest-git – packaging scripts for AUR
g. Meta Information
- version, LICENSE, .gitmodules, .gitignore

##### Component Relationships & Data Flow
- The Makefile orchestrates compilation of src/*.c + static_dependencies into a shared/static libcest.
- headers/*.h define the public interface used by:
- primitive_testing to validate library internals
- tests/*.c to verify library functionality
- client code (USER) to write their own tests or suites
- Client code or test suite constructors call into libcest via function pointers (hooks) and Assert API.
- The CI pipeline (Travis) runs `make check` to compile/tests and uses gdb/valgrind for debugging hooks.
- Deployment scripts package the built artifacts for distribution on Arch Linux.

##### Architectural Patterns & Design Principles
- Modular C design: clear separation between interface (headers) and implementation (src).
- Plugin‐style hooks: before/after suite via function pointers.
- Utility modules: linked list and memory allocator abstract away low-level details.
- Static linking of exceptions4c to avoid external runtime dependencies.
- Convention-driven build (Makefile targets) and configuration (Travis, deployment).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Test Code
    subgraph "Client/Test Code"
        direction TB
        PT["Primitive Testing Harness"]:::client
        UT["User Test Suites"]:::client
    end

    %% Public API Headers
    subgraph "Public API Headers"
        direction TB
        H1["cutest.h"]:::api
        H2["cutestsuite.h"]:::api
        H3["create_test_suite.h"]:::api
        H4["cutest_assert.h"]:::api
        H5["linkedlist.h"]:::api
        H6["mem_alloc.h"]:::api
    end

    %% Core Implementation
    subgraph "Core Implementation"
        direction TB
        C1["cutest.c"]:::impl
        C2["cutestsuite.c"]:::impl
        C3["cutest_assert.c"]:::impl
        C4["linkedlist.c"]:::impl
        C5["mem_alloc.c"]:::impl
    end

    %% Static Dependency
    subgraph "Static Dependency: exceptions4c"
        direction TB
        D1["e4c.c"]:::dep
        D2["e4c.h"]:::dep
    end

    %% Build & Artifacts
    subgraph "Build & Artifacts"
        direction TB
        MF["Makefile"]:::build
        ART["libcest.so/.a"]:::artifact
    end

    %% CI & Deployment
    subgraph "CI & Deployment"
        direction TB
        CI[".travis.yml"]:::build
        DP["deployment/archlinux/cest-git"]:::build
    end

    %% Meta
    subgraph "Meta Information"
        direction TB
        M1["LICENSE"]:::meta
        M2["version"]:::meta
        M3[".gitmodules"]:::meta
        M4[".gitignore"]:::meta
    end

    %% Relationships
    PT -->|includes| H1
    PT -->|includes| H2
    UT -->|includes| H1
    UT -->|includes| H2
    UT -->|includes| H4

    H1 -->|declares API| C1
    H2 -->|declares API| C2
    H4 -->|declares API| C3
    H5 -->|declares API| C4
    H6 -->|declares API| C5

    C1 -->|uses| D1
    C2 -->|uses| D1
    C3 -->|uses| D1
    C4 -->|uses| D1
    C5 -->|uses| D1

    MF -->|"gcc compiles"| C1
    MF -->|"gcc compiles"| C2
    MF -->|"gcc compiles"| C3
    MF -->|"gcc compiles"| C4
    MF -->|"gcc compiles"| C5
    MF -->|"link static"| D1
    MF -->|"produce"| ART

    CI -->|"runs make check"| MF
    CI -->|"invokes gdb/valgrind"| ART

    DP -->|"packages"| ART

    %% Click Events
    click C1 "https://github.com/hadichahine/cest/blob/master/src/cutest.c"
    click C2 "https://github.com/hadichahine/cest/blob/master/src/cutestsuite.c"
    click C3 "https://github.com/hadichahine/cest/blob/master/src/cutest_assert.c"
    click C4 "https://github.com/hadichahine/cest/blob/master/src/linkedlist.c"
    click C5 "https://github.com/hadichahine/cest/blob/master/src/mem_alloc.c"
    click H1 "https://github.com/hadichahine/cest/blob/master/headers/cutest.h"
    click H2 "https://github.com/hadichahine/cest/blob/master/headers/cutestsuite.h"
    click H3 "https://github.com/hadichahine/cest/blob/master/headers/create_test_suite.h"
    click H4 "https://github.com/hadichahine/cest/blob/master/headers/cutest_assert.h"
    click H5 "https://github.com/hadichahine/cest/blob/master/headers/linkedlist.h"
    click H6 "https://github.com/hadichahine/cest/blob/master/headers/mem_alloc.h"
    click D1 "https://github.com/hadichahine/cest/blob/master/static_dependencies/exceptions4c/e4c.c"
    click D2 "https://github.com/hadichahine/cest/blob/master/static_dependencies/exceptions4c/e4c.h"
    click PT "https://github.com/hadichahine/cest/blob/master/primitive_testing/primitive_testing_environment.c"
    click UT "https://github.com/hadichahine/cest/tree/master/tests/"
    click MF "https://github.com/hadichahine/cest/tree/master/Makefile"
    click CI "https://github.com/hadichahine/cest/blob/master/.travis.yml"
    click DP "https://github.com/hadichahine/cest/tree/master/deployment/archlinux/cest-git/"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#006699,color:#000;
    classDef impl fill:#98FB98,stroke:#228B22,color:#000;
    classDef dep fill:#FFA500,stroke:#CC8400,color:#000;
    classDef build fill:#DDA0DD,stroke:#993399,color:#000;
    classDef artifact fill:#FFFFFF,stroke:#0000FF,stroke-width:2px;
    classDef client fill:#F0E68C,stroke:#BDB76B,color:#000;
    classDef meta fill:#E8E8E8,stroke:#A9A9A9,color:#000;
```
