libLogit

SDK Architecture

libLogit is easiest to understand when you think of it as one portable object model with several layers around it.

The Core Idea

A LOGIT is a user-owned logging device.

That device owns:

• its name
• its local output location
• its optional remote output location
• its sink selection
• its level threshold
• its formatting rules
• its metadata
• its rotation and retention rules
• its runtime behavior such as buffering and failure policy

The project succeeds when those ideas mean the same thing everywhere, even if the syntax around them changes from Python to C++ to JavaScript.

SDK Layers

1. Public Binding Surface

This is what a user imports.

Examples:

• from liblogit import LOGIT
• new Logit()
• liblogit::LOGIT{}
• liblogit.New()

Each binding must expose blank construction, startup configuration, and a way to emit a log event.

2. Shared Contract

The contract is the language-agnostic meaning of the fields and operations:

• name
• localPath
• outputDirectory
• pathMode
• remotePath
• databasePath
• level
• sinks
• format
• metadata
• rotation
• retention

This is the part Beta must freeze.

3. Config And Schema

The config layer lets teams define many named loggers in one place.

That layer includes:

• shared JSON schema
• config defaults
• named logger registry loading
• migration rules from older config shapes
• environment override rules

4. Runtime Sinks

Sinks are where events go.

Current Alpha/Beta-track sink families:

• console
• local file
• remote path treated as file output
• SQLite database store
• future network transports

5. Conformance Layer

The conformance layer is what keeps libLogit from drifting into eight slightly different products.

It includes:

• shared fixtures
• shared expected output
• per-binding runners
• local verification scripts
• hosted CI gates

6. Viewer And SQL Workflow

The viewer is not separate from the SDK story. It is the proof that retained logs are useful after they are written.

The current shape is:

1. a LOGIT writes into a bounded SQLite store
2. any SQL tool can inspect the rows
3. the built-in viewer can open the same store for filtering and reading

Execution Flow

The ideal end-to-end flow for a user looks like this:

1. Install the binding for their language.
2. Construct a blank LOGIT or load one from config.
3. Set outputDirectory or localPath.
4. Set level.
5. Emit log events.
6. Let the SDK write to console and one or more persisted sinks.
7. Query or view retained logs later.

Why The Contract Matters More Than Syntax

Different ecosystems want different shapes:

• Python tolerates dynamic structures and builder chaining.
• C prefers functions and explicit structs.
• C++ naturally supports streaming syntax.
• JVM and .NET users expect object instances and fluent builders.
• Go users expect explicit error returns.

If libLogit forces one punctuation style everywhere, it will feel bad. If it lets the meaning drift, it stops being one SDK. Beta is where we keep the meaning stable and let the syntax stay native.

Alpha Versus Beta Architecture Goals

Alpha

Alpha proves:

• the model is worth building
• users can instantiate and call a logger
• logs can land in console and files
• a local SQLite-backed retained store is viable
• a simple viewer can sit on top of that store

Beta

Beta must harden:

• the contract wording
• the config/schema vocabulary
• fixture coverage
• packaging
• OS/runtime validation
• consumer install stories
• public documentation

Files That Carry The Architecture

Topic	Primary file
Public product framing	README.md
Docs home	docs/README.md
API surface	docs/api/README.md
Public contract matrix	docs/beta/contract-matrix.md
Public schema audit	docs/beta/schema-audit.md
Public lifecycle/compatibility rules	docs/beta/lifecycle-and-compatibility.md
Public binding compatibility matrix	docs/beta/binding-compatibility-matrix.md
Public error taxonomy	docs/beta/error-taxonomy.md
Public schema-version strategy	docs/beta/schema-version-strategy.md
Shared contract	spec/logit-object.md
Config shape	schema/logit.v2.schema.json
Binding rules	docs/beta/binding-playbook.md
Delivery plan	docs/burndown.md