Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
58 lines (41 loc) · 2.12 KB

ARCHITECTURE.md

File metadata and controls

58 lines (41 loc) · 2.12 KB
Raw

Architecture

Model

@codectyl/agnostic-core owns the external seams of the system. Each seam is a vendor-neutral port such as StoragePort or AuthPort.

An adapter satisfies a port. Adapters contain SDK imports, connection setup, query details, serialization choices, and vendor-specific error handling.

@codectyl/agnostic-adapter-* ──depends on──> @codectyl/agnostic-core

Core never imports an adapter or a vendor SDK.

Core package

@codectyl/agnostic-core contains AuthPort, CachePort, QueuePort, StoragePort, FileReference, and FileReferenceSchema. It also contains the dependency-free InMemoryCache and LocalAsyncQueue implementations.

StoragePort operates on paths. Bucket names, namespaces, and other storage layout decisions belong to the adapter configuration rather than the core interface.

The Port suffix identifies a contract. Concrete classes should use a name such as SupabaseStorageAdapter.

Adapter packages

Use one package per meaningful vendor or infrastructure dependency:

packages/adapter-supabase → @codectyl/agnostic-adapter-supabase
packages/adapter-redis    → @codectyl/agnostic-adapter-redis
packages/adapter-s3       → @codectyl/agnostic-adapter-s3

Do not create an adapter package for code with no external dependency that can be shared safely from core. Examples include local caches and queues.

Adding an adapter

  1. Confirm the behavior varies by vendor or external dependency.
  2. Add @codectyl/agnostic-adapter-<vendor> as a workspace package.
  3. Depend on @codectyl/agnostic-core through the workspace protocol.
  4. Implement one or more core ports with explicit adapter classes.
  5. Keep vendor types at the adapter edge and return core types.
  6. Add contract tests for the selected port.
  7. Document configuration, lifecycle, errors, and unsupported operations.

Domain-specific persistence

There is currently no database port. Persistence contracts should be added only when the domain entities and operations are defined clearly enough to make a useful vendor-neutral interface. Do not add a generic pass-through database client to core.