Skip to main content

Repository Guide

Repository Purpose​

cortexa.connectors is a private TypeScript npm workspace for Cortexa connector packages. Its current implementation scope is a provider-oriented package repository with one implemented package: @cortexa/connectors-google-drive.

The repository contains workspace configuration, shared TypeScript defaults, repository documentation, a generated repository tree, one Google Drive provider package, provider-local examples, and a script for regenerating the project tree. It is a library workspace, not a runtime application, UI application, deployment surface, persistence owner, or documentation-only repository.

Use this document as the authoritative repository navigation and code placement guide. Use docs/ARCHITECTURE.md for architectural responsibilities, system boundaries, ecosystem role, design principles, and non-goals.

Repository Organization Overview​

The repository is organized as a small npm workspace monorepo. The root owns workspace metadata, dependency locking, shared compiler defaults, and repository-level scripts. Provider connector implementations live under packages/* as independent package directories.

The current repository-level organization is package-based. The implemented package uses a layer-based internal layout:

  • src/index.ts owns public exports.
  • src/google-drive.connector.ts owns the public connector facade.
  • src/client owns provider SDK client construction.
  • src/services owns provider operations.
  • src/mappers owns provider-to-contract mapping.
  • src/types owns package-local TypeScript option types.
  • examples owns package-local development examples.

There are no runtime apps, UI apps, database modules, infrastructure folders, test suites, or deployment configuration folders in the current repository tree.

Estructura de la solución​

The stable solution structure is:

  • Root workspace files define package discovery, dependency locking, shared TypeScript defaults, ignore rules, and repository scripts.
  • docs contains durable repository-level documentation.
  • docs/repository/project-tree.md contains the generated current file and folder inventory.
  • packages contains npm workspace packages.
  • packages/google-drive contains the implemented Google Drive provider connector package.
  • packages/google-drive/src contains package source included in the TypeScript build.
  • packages/google-drive/examples contains development examples that exercise the package from source.
  • scripts contains repository tooling, currently the project-tree generator.

Canonical source areas are the root configuration files, docs/REPOSITORY.md, docs/ARCHITECTURE.md, packages/google-drive/src, packages/google-drive/package.json, packages/google-drive/tsconfig.json, packages/google-drive/README.md, root README.md, root package.json, root tsconfig.base.json, .gitignore, and scripts under scripts.

Generated or non-canonical areas include docs/repository/project-tree.md, node_modules, package dist outputs, build, coverage, TypeScript build info files, logs, temporary folders, local environment files, package archives, and local tool state such as .agents.

Provider implementations belong under packages/<provider>. Provider-specific clients, services, mappers, types, examples, and dependencies should stay inside the provider package. Shared Cortexa contracts are not defined here; packages import them from @cortexa/contracts.

Package manifests and build configuration are located at:

  • package.json for root workspace metadata and root scripts.
  • package-lock.json for npm dependency locking.
  • tsconfig.base.json for shared TypeScript compiler defaults.
  • packages/google-drive/package.json for the Google Drive package manifest, package build script, package dependencies, and published entry metadata.
  • packages/google-drive/tsconfig.json for package compiler configuration.

The observable public package entrypoint is packages/google-drive/src/index.ts. The built package manifest points runtime and type consumers at dist/index.js and dist/index.d.ts, which are generated build outputs.

Use docs/REPOSITORY.md for stable repository explanation. Use docs/repository/project-tree.md for the exhaustive generated technical inventory of current files and folders.

High-Level Repository Tree​

The complete generated tree is in docs/repository/project-tree.md. This high-level tree shows only the main navigational areas:

.
|-- docs/
|   |-- repository/
|   |   +-- project-tree.md
|   |-- ARCHITECTURE.md
|   +-- REPOSITORY.md
|-- packages/
|   +-- google-drive/
|       |-- examples/
|       |-- src/
|       |   |-- client/
|       |   |-- mappers/
|       |   |-- services/
|       |   |-- types/
|       |   |-- google-drive.connector.ts
|       |   +-- index.ts
|       |-- package.json
|       |-- README.md
|       +-- tsconfig.json
|-- scripts/
|   +-- generate-project-tree.ps1
|-- .gitignore
|-- package.json
|-- package-lock.json
|-- README.md
+-- tsconfig.base.json

Top-Level Directory Responsibilities​

docs​

Responsibility: repository-level documentation.

What belongs there: durable documentation that applies to the repository as a whole, including architectural guidance, repository organization guidance, and generated repository inventory.

What should not belong there: provider-specific usage examples, package-private implementation notes, dependency folders, build output, runtime data, or exhaustive hand-maintained file listings.

Relationship with other areas: docs/ARCHITECTURE.md owns architecture; docs/REPOSITORY.md owns repository organization; docs/repository/project-tree.md is generated from the current filesystem by the script in scripts.

packages​

Responsibility: npm workspace packages.

What belongs there: provider connector packages with package-local source, manifests, TypeScript configuration, README files, examples, and provider-specific dependencies.

What should not belong there: root workspace configuration, repository-level docs, deployment infrastructure, consumer application workflows, or generated dependency folders.

Relationship with other areas: root package.json discovers packages through packages/*. Package TypeScript configuration extends tsconfig.base.json.

scripts​

Responsibility: repository tooling.

What belongs there: scripts that support repository maintenance, documentation generation, or workspace-level automation.

What should not belong there: connector runtime code, provider SDK implementation, package public APIs, or generated output.

Relationship with other areas: scripts/generate-project-tree.ps1 writes docs/repository/project-tree.md. That generated Markdown file should not be edited manually.

Root Files​

Responsibility: workspace identity, shared configuration, dependency locking, ignore rules, and repository entrypoint documentation.

What belongs there: README.md, package.json, package-lock.json, tsconfig.base.json, and .gitignore.

What should not belong there: provider implementation source, package-local examples, package build output, local environment files, or one-off diagnostic artifacts.

Relationship with other areas: root configuration coordinates package discovery and compiler defaults; package directories contain implementation.

Package Directory Responsibilities​

packages/google-drive​

Package path: packages/google-drive.

Package purpose: Google Drive provider connector package for Cortexa connector consumers.

Source folder: packages/google-drive/src.

Public source entrypoint: packages/google-drive/src/index.ts, which exports GoogleDriveConnector and ListFilesOptions.

Built package entrypoints: dist/index.js and dist/index.d.ts, as declared in packages/google-drive/package.json. The dist folder is generated by the package build and is not canonical source.

Internal folders:

  • src/client: Google Drive SDK client construction.
  • src/services: provider operations such as listing files, listing folder contents, and downloading files.
  • src/mappers: conversion from Google Drive API file objects to Cortexa connector contract shapes.
  • src/types: package-owned option types.

Package manifest: packages/google-drive/package.json.

Package-specific README: packages/google-drive/README.md.

Examples folder: packages/google-drive/examples.

Build configuration: packages/google-drive/tsconfig.json, which extends the root tsconfig.base.json, uses src as rootDir, and emits generated output to dist.

Modules And Package Organization​

Root Workspace​

Purpose: coordinate the connector package workspace.

Responsibility: define workspace package discovery, root dependencies, shared TypeScript defaults, dependency locking, root documentation, and repository scripts.

Reusability level: repository tooling only; consumers do not import the root workspace.

Organizational relationships: points to packages through packages/* and provides shared compiler defaults to packages.

Dependency relationships: root dependencies include shared development tooling and @cortexa/contracts as a local file dependency. Provider-specific SDK dependencies should stay package-local unless they are shared by multiple provider packages.

@cortexa/connectors-google-drive​

Purpose: implement the Google Drive provider connector package.

Responsibility: expose the package public connector API, create Google Drive API clients from caller-supplied access tokens, implement provider operations, map provider metadata to Cortexa contract types, and keep Google Drive SDK details inside the package.

Reusability level: reusable library package for Cortexa consumers.

Organizational relationships: lives under the workspace packages directory and owns its source, examples, manifest, package README, and package TypeScript configuration.

Dependency relationships: depends on googleapis for Google Drive API access and imports shared connector types from @cortexa/contracts.

Public entrypoints or exports: src/index.ts exports from src/google-drive.connector.ts and src/types/list-files-options.ts.

Classification: provider-specific implementation package.

Dependency And Boundary Rules​

The repository-level dependency boundaries currently reflected in implementation are:

  • Root workspace configuration coordinates packages; provider implementation code belongs in packages.
  • Provider packages import shared Cortexa contract types from @cortexa/contracts.
  • Provider packages may depend on provider SDKs, such as googleapis.
  • Public package exports are routed through src/index.ts.
  • Provider SDK request details stay inside provider package clients and services.
  • Provider-to-Cortexa metadata conversion stays in provider package mappers.
  • Package-local examples are development aids and are not the public package contract.
  • Generated outputs are not canonical source and should not be edited manually.

Do not place shared Cortexa contract definitions inside provider packages. Do not return raw provider SDK objects through the public connector API unless the public contract is intentionally changed and documented elsewhere. Do not add persistence, indexing, scheduling, deployment, UI, or product workflow code to this repository under the current structure.

Shared vs Implementation-Specific Components​

Shared infrastructure in this repository consists of the root workspace manifest, lockfile, shared TypeScript configuration, ignore rules, repository scripts, and repository-level documentation.

Shared libraries are not currently represented as repository-local packages. If reusable code is needed across provider packages, it should be introduced as a clear workspace package under packages rather than hidden inside one provider package.

Shared contracts are external to this repository and come from @cortexa/contracts.

Provider-specific implementation currently lives in packages/google-drive. Google Drive client construction, services, mapping code, option types, examples, and provider SDK dependencies belong there.

Runtime applications, business applications, presentation layers, persistence modules, infrastructure modules, and deployment surfaces are not present in the current repository.

Generated documentation is represented by docs/repository/project-tree.md. Generated build artifacts are represented by package dist outputs when builds are run.

Generated Project Tree​

docs/repository/project-tree.md contains the generated current file and folder inventory for this repository. It complements this document:

  • docs/REPOSITORY.md explains stable repository organization, ownership, and code placement.
  • docs/repository/project-tree.md records the generated current file tree for technical navigation.

Do not edit docs/repository/project-tree.md manually. Regenerate it whenever repository structure changes.

Current generator command:

npm run docs:tree

The generator is implemented by scripts/generate-project-tree.ps1. It excludes dependency, build, coverage, local state, and temporary folders including .git, .agents, node_modules, dist, build, coverage, .next, .turbo, .cache, and .docusaurus.

The generated tree helps contributors and AI agents locate files and verify current structure without turning this repository guide into an exhaustive file listing.

Code Placement Guidance​

New provider package: add it under packages/<provider> with its own package.json, tsconfig.json, src, package README, and optional examples. Keep provider SDK dependencies in that package.

New Google Drive connector method: add the public method to packages/google-drive/src/google-drive.connector.ts, implement provider work under packages/google-drive/src/services, add package-owned options under packages/google-drive/src/types, and export consumer-facing types through packages/google-drive/src/index.ts.

New provider adapter or client behavior: place Google Drive SDK initialization and credential adapter code under packages/google-drive/src/client. Keep operation-specific provider calls in services unless they are reusable client setup behavior.

New provider-specific service: place it under packages/google-drive/src/services. Services may use src/client, src/mappers, and package-local types.

New mapper: place provider-to-contract conversion code under packages/google-drive/src/mappers.

New type or contract: place package-owned option types or interfaces under packages/google-drive/src/types. Shared Cortexa contracts belong in @cortexa/contracts, not in this repository.

New public package export: add it to packages/google-drive/src/index.ts only when it is intended for consumers.

New utility: keep provider-specific utilities inside the provider package. For cross-provider utilities, add a deliberately named workspace package under packages only when more than one provider package needs it.

New example: add it under packages/google-drive/examples or the relevant provider package's examples folder. Examples should remain development-oriented and separate from production source.

New test: no test directory or test convention is currently represented. If tests are added, place package-specific tests with the owning package and update this guide with the adopted convention.

New script: add repository-level tooling under scripts when it applies to the workspace. Add package-level scripts to the owning package manifest when they apply only to one package.

New generated documentation artifact: place generated repository inventory under docs/repository and regenerate it with the documented command. Do not manually edit generated files.

New documentation page: add repository-level guidance under docs. Add package-specific purpose, usage, exports, examples, and package-local setup guidance to the package README.

New build or tooling configuration: put shared TypeScript defaults in tsconfig.base.json, package-specific TypeScript settings in the package tsconfig.json, workspace scripts in root package.json, and package scripts in the package manifest.

Do not add UI components, API service endpoints, database schema, migration files, background jobs, deployment manifests, or product-specific workflow code to this repository unless the repository scope changes and the architecture documentation is updated.

Repository Conventions​

Observed conventions:

  • The repository is private and uses npm workspaces.
  • Workspace packages are discovered from packages/*.
  • Provider package names use the @cortexa/connectors-<provider> pattern.
  • Provider packages use TypeScript source under src.
  • Package builds emit generated output to dist.
  • Package main and types fields point to generated dist entrypoints.
  • Root TypeScript defaults live in tsconfig.base.json.
  • Package TypeScript configuration extends the root TypeScript configuration.
  • Public package exports are routed through src/index.ts.
  • Connector facade files use the provider name and .connector.ts.
  • Provider SDK client construction lives under src/client.
  • Provider operations live under src/services.
  • Provider response mapping lives under src/mappers.
  • Package-owned option types live under src/types.
  • Package examples live under examples.
  • The generated project tree is created by npm run docs:tree and is not edited manually.
  • Generated, dependency, local, and temporary folders are excluded from the generated tree.

Current observed usage does not establish a test convention, shared local library convention, application convention, database convention, or UI convention.

Generated, Dependency, Local, And Temporary Areas​

The following areas are not canonical source:

  • docs/repository/project-tree.md: generated documentation inventory.
  • node_modules: installed dependencies.
  • dist: package build output.
  • build: generated build output when present.
  • coverage: generated test coverage output when present.
  • *.tsbuildinfo: generated TypeScript incremental build state.
  • .git: version-control internals.
  • .agents: local tool state.
  • .next, .turbo, .cache, .docusaurus: local or generated tool output when present.
  • .env and .env.*: local environment files, except committed examples such as .env.example.
  • logs, *.log, package manager debug logs, tmp, temp, PID files, and generated package archives.

These areas should not be used as source-of-truth inputs for repository organization. Generated outputs should be recreated from source and scripts instead of edited manually.

Documentation Corpus Map​

README.md: repository landing page for quick orientation, getting started notes, repository summary, and documentation entrypoint.

docs/ARCHITECTURE.md: architectural source of truth for module purpose, responsibilities, boundaries, ecosystem role, constraints, non-goals, and integration semantics.

docs/REPOSITORY.md: repository organization source of truth for folder responsibilities, package layout, code placement, repository conventions, and generated tree workflow.

docs/repository/project-tree.md: generated current repository tree and exhaustive technical file and folder inventory for contributors and AI agents.

packages/google-drive/README.md: package-level README for Google Drive connector package details. It is currently present but empty.

There is no docs/DATABASE.md, docs/ECOSYSTEM.md, docs/API.md, or docs/OPERATIONS.md in the current repository. Do not reference those as current repository documents unless they are added.

Guidance For Developers And AI Agents​

Start with README.md for orientation, then use docs/ARCHITECTURE.md for architectural boundaries and this document for code navigation.

Use docs/repository/project-tree.md when you need the exhaustive current file inventory. Regenerate it with npm run docs:tree before relying on it after structural changes.

Locate package entrypoints through package manifests and src/index.ts. For the current package, start at packages/google-drive/src/index.ts and packages/google-drive/src/google-drive.connector.ts.

Locate provider-specific implementation under the owning provider package. For Google Drive, use packages/google-drive/src/client, src/services, src/mappers, and src/types.

Place shared abstractions only where the repository structure supports sharing. Do not hide shared cross-provider code inside packages/google-drive. Do not place provider-specific behavior in root workspace files or future shared packages.

Keep examples under package-local examples directories. Keep scripts under scripts when they operate at repository level. Keep package-level setup and usage details in package READMEs.

Avoid treating generated output as source. Do not edit docs/repository/project-tree.md or dist files manually. Do not add dependency folders, local state, coverage output, logs, temporary files, or environment secrets to the source tree.

Avoid placing product-specific behavior inside this platform module. Consumer application workflows, persistence, indexing, scheduling, UI, deployment, observability policy, and credential lifecycle management belong outside the current repository scope.

Documentation Standards​

This document must reflect only the repository organization that exists now. Do not describe planned providers, future applications, speculative shared packages, or ideal architecture as current structure.

Keep this guide focused on repository navigation, organizational ownership, package placement, code placement, conventions, and generated versus canonical documentation separation.

Do not use this document as an architecture document, domain model, database reference, deployment guide, feature inventory, changelog, task plan, or low-level implementation walkthrough.

Update this guide when folders, packages, package entrypoints, code placement conventions, generated documentation workflows, long-lived examples, scripts, or package-level structure change. Routine implementation changes inside existing structures should not require significant updates.

Repository Document Principles​

docs/REPOSITORY.md should remain the primary repository navigation guide for developers, technical reviewers, new contributors, AI coding agents, documentation systems, knowledge platforms, and future Cortexa maintainers.

It should evolve with repository structure and stay aligned with the generated tree, package manifests, public exports, and current implementation. Stable explanation belongs here; exhaustive generated inventory belongs in docs/repository/project-tree.md.