# ashutoshbw/neotoc architecture

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

- Interactive diagram: https://gitdiagram.com/ashutoshbw/neotoc
- Repository: https://github.com/ashutoshbw/neotoc

## Overview

##### Main Components
- Website (Frontend): Located under the apps/www directory, this part of the project hosts the documentation, demos, and interactive examples. It uses Next.js (as seen from next.config.ts and pages like page.tsx) and integrates UI components (located under src/components and src/app).
- Core Library (neotoc): Found in packages/neotoc. This package implements the core functionality such as generating animated, foldable tables of contents (see various source files like autoFold.ts, highlight.ts, etc.). It also includes CSS styling files and tests.
- CLI/Scaffolding Tool (create-neotoc): Found in packages/create-neotoc. This segment allows users to quickly set up a Vision-supported Neotoc playground using Vite, integrating user prompts, scaffolding files, and a template for basic usage.
- Build/Configuration & GitHub Workflows: Configurations (e.g., .github/workflows, turbo.json, pnpm-workspace.yaml) that indicate how the repository is built, tested, and deployed. Although not a “runtime” component, these are crucial for the project’s pipeline.
- Package Manager & Monorepo Setup: The presence of pnpm-lock.yaml and workspace configuration indicates that the project uses a monorepo pattern for managing different packages.

##### Relationships and Interactions
- The website (apps/www) consumes the Neotoc package to demonstrate its features to users. It likely interacts with the core library via client-side code.
- The CLI scaffolding tool (create-neotoc) depends on the core Neotoc functionalities to configure a new project and quickly expose users to a ready-to-run environment.
- The monorepo structure enables shared dependencies, configuration, and build scripts across these packages, managed through tools like Turborepo.
- The build/deployment pipeline (via GitHub workflows) orchestrates tasks for linting, testing, bundling, and releasing packages to NPM/GitHub.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each package (neotoc and create-neotoc) is decoupled. This allows for individual development and testing while sharing a unified codebase.
- Clear Separation of Concerns: The frontend (website) is distinct from the core logic (neotoc) and developer tooling (create-neotoc).
- Monorepo/Workspace: The use of a monorepo ensures consistency in versioning, testing, and dependency management across the ecosystem.
- Reusability and Extensibility: The structure of the packages, along with clear configuration (e.g., ESLint, Prettier, Tailwind), shows an emphasis on extending and integrating the functionality across new projects.

##### Relevant Technologies and Frameworks
- Next.js, React, Tailwind CSS (for the website).
- Node.js and CLI tools (for the scaffold with npx create-neotoc).
- Turborepo and pnpm for monorepo management.
- JavaScript/TypeScript for core logic, with ESLint and Prettier ensuring code quality.
- Testing frameworks (Vitest as seen in vitest.config.ts) to run unit tests.

##### Detailed Steps for Creation
c. CLI tool as a separate node that also interacts with the Core Library for scaffolding a new project.
d. Around these central components, include auxiliary nodes for build pipelines and repository management (monorepo structure, GitHub workflows, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configurations & Monorepo Setup
    config1["GitHub Workflows"]:::config
    config2["Turbo Config"]:::config
    config3["Workspace Config"]:::config
    config4["Pnpm Lock"]:::config

    %% Monorepo Packages
    website["Website (apps/www)"]:::frontend
    core["Core Library (Neotoc)"]:::backend
    cli["CLI/Scaffolding Tool (create-neotoc)"]:::cli

    %% Configuration to Packages Connections
    config1 -->|"affects"| website
    config1 -->|"affects"| core
    config1 -->|"affects"| cli

    config2 -->|"affects"| website
    config2 -->|"affects"| core
    config2 -->|"affects"| cli

    config3 -->|"affects"| website
    config3 -->|"affects"| core
    config3 -->|"affects"| cli

    config4 -->|"affects"| website
    config4 -->|"affects"| core
    config4 -->|"affects"| cli

    %% Interactions between Packages
    website -->|"consumes"| core
    cli -->|"scaffolds using"| core

    %% Click Events for Components
    click website "https://github.com/ashutoshbw/neotoc/tree/main/apps/www"
    click core "https://github.com/ashutoshbw/neotoc/tree/main/packages/neotoc"
    click cli "https://github.com/ashutoshbw/neotoc/tree/main/packages/create-neotoc"
    click config1 "https://github.com/ashutoshbw/neotoc/tree/main/.github/workflows"
    click config2 "https://github.com/ashutoshbw/neotoc/blob/main/turbo.json"
    click config3 "https://github.com/ashutoshbw/neotoc/blob/main/pnpm-workspace.yaml"
    click config4 "https://github.com/ashutoshbw/neotoc/blob/main/pnpm-lock.yaml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#1F77B4,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#2CA02C,stroke-width:2px;
    classDef cli fill:#FFD580,stroke:#FF7F0E,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
```
