How segararai/fraci works
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).