# segararai/fraci architecture

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

- Interactive diagram: https://gitdiagram.com/segararai/fraci
- Repository: https://github.com/segararai/fraci

## Overview

##### Main Components
- Core Fractional Indexing Engine – This is the central logic (including both string‐ and binary–based implementations) that performs index generation, conflict resolution, and type safety via branded types. In the file tree, look at files in the “src/”, “src/lib/”, and “src/factory.ts” that contain the actual algorithms.
- ORM Integration Modules – There are two major integration components:
– Drizzle ORM Integration (found in “fraci/drizzle”, “src/drizzle/”, and the examples under “examples/drizzle-orm*”). This layer wraps the core engine, provides helper functions (like drizzleFraci, defineDrizzleFraci), and applies the fractional indexing to tables.
– Prisma ORM Integration (files in “fraci/prisma” and examples under “examples/prisma”). This extension configures and integrates the fractional indexing with the Prisma schema.
- Database Migrations & Schema – The “drizzle” and “prisma” directories with migration files and schema definitions show how the database tables are structured (for example, the compound index on [group, fractional index]) for performance and uniqueness.
- Example Applications & Testing – The “examples/” and “test/” directories supply code samples and test scripts that illustrate usage and validate correct ordering of indices.
- Build & CI/Configuration – Files like “tsconfig.json”, “package.json”, and GitHub Actions workflows in “.github/workflows” illustrate the build pipelines, testing, and continuous integration that support the project.

##### Out Relationships & Data Flows
- Two main “entry points” from application code: one branch for Drizzle ORM and another for Prisma ORM.
- That the core engine supports both string and binary representations. Use separate branches or annotations that distinguish the two modes.
- A feedback loop for conflict resolution – if a generated index conflicts (detected via ORM error handling logic), the integration module calls the core engine again to generate a new index.

##### Architectural Patterns & Design Principles
- Modularity: The system is clearly modularized into a core library and integration modules. Emphasize that the fractional indexing algorithm is built to be extensible via well-defined APIs.
- Type Safety: Incorporate a note or symbol that indicates the use of branded types and strict TypeScript type checking (found in the README and multiple .ts files).
- Conflict Resolution and Retry Logic: Represent the “retry loop” mechanism that both ORM integrations use when unique constraint violations occur.
- Separation of Concerns: Show separate components for business logic (index generation), database schema management (migrations), and external integration (ORM extensions).

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Client Application"]:::client
    Drizzle["Drizzle ORM Integration"]:::drizzle
    Prisma["Prisma ORM Integration"]:::prisma
    Core["Fraci Core Engine (String & Binary Modes)"]:::core
    DB["Database/Migrations (Compound Indexes)"]:::db
    Test["Examples & Tests"]:::test
    CI["Build & CI/Configuration"]:::ci

    Client -->|"calls"| Drizzle
    Client -->|"calls"| Prisma
    Drizzle -->|"calls_core"| Core
    Prisma -->|"calls_core"| Core
    Core -->|"generates_index"| DB
    DB -.->|"retry"| Core
    Test -->|"tests"| Core
    CI -->|"builds_tests"| Test

    click Core "https://github.com/segararai/fraci/blob/main/src/factory.ts"
    click Core "https://github.com/segararai/fraci/blob/main/src/index.ts"
    click Core "https://github.com/segararai/fraci/blob/main/src/lib/fractional-indexing-string.ts"
    click Core "https://github.com/segararai/fraci/blob/main/src/lib/fractional-indexing-binary.ts"
    click Core "https://github.com/segararai/fraci/blob/main/src/lib/types.ts"
    click Core "https://github.com/segararai/fraci/blob/main/src/lib/utils.ts"

    click Drizzle "https://github.com/segararai/fraci/blob/main/src/drizzle/index.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/src/drizzle/common.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/src/drizzle/runtime.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/src/drizzle/runtime-sync.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/drizzle.config.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/drizzle/e2e-string.config.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/drizzle/e2e-binary.config.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/examples/drizzle-orm/index-performance.string.test.ts"
    click Drizzle "https://github.com/segararai/fraci/blob/main/examples/drizzle-orm/server.string.ts"

    click Prisma "https://github.com/segararai/fraci/blob/main/src/prisma/index.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/src/prisma/common.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/src/prisma/extension.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/src/prisma/constants.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/examples/prisma/client.string.test.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/examples/prisma/server.string.ts"
    click Prisma "https://github.com/segararai/fraci/blob/main/prisma/schema.prisma"
    click Prisma "https://github.com/segararai/fraci/tree/main/prisma/migrations"

    click DB "https://github.com/segararai/fraci/tree/main/drizzle/migrations"
    click DB "https://github.com/segararai/fraci/blob/main/drizzle/migrations.e2e-string"
    click DB "https://github.com/segararai/fraci/blob/main/drizzle/migrations.e2e-binary"
    click DB "https://github.com/segararai/fraci/blob/main/drizzle/schema.ts"
    click DB "https://github.com/segararai/fraci/blob/main/drizzle/schema.e2e-string.ts"
    click DB "https://github.com/segararai/fraci/blob/main/drizzle/schema.e2e-binary.ts"
    click DB "https://github.com/segararai/fraci/tree/main/prisma/migrations"
    click DB "https://github.com/segararai/fraci/blob/main/prisma/schema.prisma"

    click Test "https://github.com/segararai/fraci/tree/main/examples/core-only"
    click Test "https://github.com/segararai/fraci/tree/main/examples/drizzle-orm"
    click Test "https://github.com/segararai/fraci/tree/main/examples/drizzle-orm-sync"
    click Test "https://github.com/segararai/fraci/tree/main/examples/prisma"
    click Test "https://github.com/segararai/fraci/tree/main/examples/common"
    click Test "https://github.com/segararai/fraci/tree/main/test"
    click Test "https://github.com/segararai/fraci/blob/main/src/factory.test.ts"
    click Test "https://github.com/segararai/fraci/blob/main/src/lib/*.test.ts"

    click CI "https://github.com/segararai/fraci/blob/main/tsconfig.json"
    click CI "https://github.com/segararai/fraci/blob/main/tsup.config.ts"
    click CI "https://github.com/segararai/fraci/blob/main/package.json"
    click CI "https://github.com/segararai/fraci/blob/main/bun.lock"
    click CI "https://github.com/segararai/fraci/tree/main/.github/workflows"
    click CI "https://github.com/segararai/fraci/blob/main/.editorconfig"
    click CI "https://github.com/segararai/fraci/blob/main/.prettierrc"

    classDef client fill:#81A1C1,stroke:#2E3440,stroke-width:2px;
    classDef drizzle fill:#88C0D0,stroke:#2E3440,stroke-width:2px;
    classDef prisma fill:#B48EAD,stroke:#2E3440,stroke-width:2px;
    classDef core fill:#A3BE8C,stroke:#2E3440,stroke-width:2px;
    classDef db fill:#EBCB8B,stroke:#2E3440,stroke-width:2px;
    classDef test fill:#D08770,stroke:#2E3440,stroke-width:2px;
    classDef ci fill:#5E81AC,stroke:#2E3440,stroke-width:2px;
```
