# air5005/usg architecture

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

- Interactive diagram: https://gitdiagram.com/air5005/usg
- Repository: https://github.com/air5005/usg

## Overview

usg is a general-purpose C library of sorting, synchronization, timing, and ring-buffer utilities; the README does not describe a larger application workflow. Callers use these APIs directly. The sampled bubble-sort implementation calls a swap helper; other module internals were not sampled, so their connections are not inferred.

Main entry points: [`libs/libalgo/bubble_sort.c`](https://github.com/air5005/usg/blob/master/libs/libalgo/bubble_sort.c) (Bubble sort), [`libs/libalgo/quick_sort.c`](https://github.com/air5005/usg/blob/master/libs/libalgo/quick_sort.c) (Quick sort), [`libs/liblock/usg_atomic.h`](https://github.com/air5005/usg/blob/master/libs/liblock/usg_atomic.h) (Atomic operations), [`libs/liblock/usg_spinlock.h`](https://github.com/air5005/usg/blob/master/libs/liblock/usg_spinlock.h) (Spinlock)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_algorithms["Sorting"]
  node_bubble["Bubble sort<br/>[bubble_sort.c]"]
  node_quick["Quick sort<br/>[quick_sort.c]"]
end

subgraph group_concurrency["Synchronization"]
  node_atomic["Atomic operations<br/>[usg_atomic.h]"]
  node_spinlock["Spinlock<br/>[usg_spinlock.h]"]
  node_lock["Lock<br/>[usg_lock.c]"]
  node_rwlock["Read-write lock<br/>[usg_rwlock.c]"]
end

subgraph group_timing["Cycle timing"]
  node_cycles["Cycle timing<br/>[usg_cycles.c]"]
end

subgraph group_buffers["Ring buffer"]
  node_ring["Ring buffer<br/>[usg_ring.c]"]
end

subgraph group_shared["Shared utilities"]
  node_util["Sort swap helpers<br/>[usg_util.h]"]
  node_common["Common definitions<br/>[usg_common.h]"]
end

node_caller(("Library caller"))

node_caller -->|"uses"| node_bubble
node_caller -->|"uses"| node_quick
node_caller -->|"uses"| node_atomic
node_caller -->|"uses"| node_spinlock
node_caller -->|"uses"| node_lock
node_caller -->|"uses"| node_rwlock
node_caller -->|"uses"| node_cycles
node_caller -->|"uses"| node_ring
node_bubble -->|"calls"| node_util

click node_bubble "https://github.com/air5005/usg/blob/master/libs/libalgo/bubble_sort.c"
click node_quick "https://github.com/air5005/usg/blob/master/libs/libalgo/quick_sort.c"
click node_atomic "https://github.com/air5005/usg/blob/master/libs/liblock/usg_atomic.h"
click node_spinlock "https://github.com/air5005/usg/blob/master/libs/liblock/usg_spinlock.h"
click node_lock "https://github.com/air5005/usg/blob/master/libs/liblock/usg_lock.c"
click node_rwlock "https://github.com/air5005/usg/blob/master/libs/liblock/usg_rwlock.c"
click node_cycles "https://github.com/air5005/usg/blob/master/libs/libcycles/usg_cycles.c"
click node_ring "https://github.com/air5005/usg/blob/master/libs/libring/usg_ring.c"
click node_util "https://github.com/air5005/usg/blob/master/libs/libutil/usg_util.h"
click node_common "https://github.com/air5005/usg/blob/master/libs/include/usg_common.h"

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_bubble,node_quick toneBlue
class node_atomic,node_spinlock,node_lock,node_rwlock toneAmber
class node_cycles toneMint
class node_ring toneRose
class node_util,node_common,node_caller toneIndigo
```

## Components

### Sorting

- [Bubble sort](https://github.com/air5005/usg/blob/master/libs/libalgo/bubble_sort.c): `libs/libalgo/bubble_sort.c`
- [Quick sort](https://github.com/air5005/usg/blob/master/libs/libalgo/quick_sort.c): `libs/libalgo/quick_sort.c`

### Synchronization

- [Atomic operations](https://github.com/air5005/usg/blob/master/libs/liblock/usg_atomic.h): `libs/liblock/usg_atomic.h`
- [Spinlock](https://github.com/air5005/usg/blob/master/libs/liblock/usg_spinlock.h): `libs/liblock/usg_spinlock.h`
- [Lock](https://github.com/air5005/usg/blob/master/libs/liblock/usg_lock.c): `libs/liblock/usg_lock.c`
- [Read-write lock](https://github.com/air5005/usg/blob/master/libs/liblock/usg_rwlock.c): `libs/liblock/usg_rwlock.c`

### Cycle timing

- [Cycle timing](https://github.com/air5005/usg/blob/master/libs/libcycles/usg_cycles.c): `libs/libcycles/usg_cycles.c`

### Ring buffer

- [Ring buffer](https://github.com/air5005/usg/blob/master/libs/libring/usg_ring.c): `libs/libring/usg_ring.c`

### Shared utilities

- [Sort swap helpers](https://github.com/air5005/usg/blob/master/libs/libutil/usg_util.h): `libs/libutil/usg_util.h`
- [Common definitions](https://github.com/air5005/usg/blob/master/libs/include/usg_common.h): `libs/include/usg_common.h`

### Other components

- **Library caller**

## Connections

- Library caller → Bubble sort: uses
- Library caller → Quick sort: uses
- Library caller → Atomic operations: uses
- Library caller → Spinlock: uses
- Library caller → Lock: uses
- Library caller → Read-write lock: uses
- Library caller → Cycle timing: uses
- Library caller → Ring buffer: uses
- Bubble sort → Sort swap helpers: calls