@classytic/directory

Source-available business-directory kernel for MongoDB. It models directory sites, businesses, locations, taxonomy, published listings, ownership claims, verified-owner editing, regulated-provider applications, media references, and geographic discovery.

The package is framework-independent: it contains Mongoose models, MongoKit repositories, domain transitions, and Zod schemas. HTTP, authentication, permissions, storage providers, and frontend behavior belong in the consuming host or @spinekit/directory.

Design

• One directory operator deployment by default; row-level tenancy is opt-in.
• Business identity is separate from its publication as a directory listing.
• Businesses may have physical, service-area, or online locations.
• Listing publication and verification transitions use atomic compare-and-set repository operations.
• Ownership approval transfers the listing and business to the claimant in one transaction.
• Rejected claims remain immutable; corrections create a linked resubmission.
• Provider applications snapshot a versioned verification template, keep evidence separate from public listings, and recheck Media references at final approval.
• Media is stored as ExternalRef values. This kernel does not select or call a media-storage provider.
• Geo coordinates use the shared Classytic address/GeoJSON primitives and MongoDB 2dsphere indexes.

Installation

npm install @classytic/directory mongoose @classytic/mongokit \
  @classytic/primitives @classytic/repo-core zod

Node.js 22 or newer is required.

Quick start

import mongoose from 'mongoose';
import { defineDirectory } from '@classytic/directory';

await mongoose.connect(process.env.MONGODB_URI!);

const blueprint = defineDirectory({
  tenant: false,
  autoIndex: process.env.NODE_ENV !== 'production',
});

const directory = blueprint.bind(mongoose.connection);

const site = await directory.repositories.site.create({
  slug: 'dhaka-services',
  name: 'Dhaka Services',
  status: 'active',
  defaultLocale: 'en',
  defaultTimezone: 'Asia/Dhaka',
});

const business = await directory.repositories.business.create({
  name: 'Example Plumbing',
  source: 'operator',
});

await directory.syncIndexes();

The host owns the Mongoose connection. Calling directory.close() therefore does not close the shared connection.

Ownership claims

Claim submission, approval, rejection, and resubmission are exposed through directory.claims. Approval updates the claim, listing verification, listing owner, and business owner transactionally.

MongoDB transactions require a replica set. Development-only standalone MongoDB can be opted into explicitly:

const directory = defineDirectory().bind(mongoose.connection, {
  allowNonTransactional: true,
});

Do not use that fallback when atomic ownership transfer is required.

Tenancy

The default is a single directory deployment:

defineDirectory({ tenant: false });

Reusable hosts that genuinely require field tenancy may pass a standard TenantConfig through tenant. Listed businesses and claimants are content and users; they are not automatically tenants.

Exports

• @classytic/directory — engine, repositories, document types, shared primitive aliases, and domain services.
• @classytic/directory/schemas — strict Zod request/value schemas.

For Arc resources, safe public projections, owner routes, and frontend wire contracts, use @spinekit/directory.

License

This package is source-available, not open source. Evaluation and development use are permitted under the included license. Production use requires a commercial license from Classytic LLC. See LICENSE or contact [email protected].