Repository Guide

Repository Purpose

@cortexa/auth is a TypeScript npm package that provides reusable external OAuth authentication infrastructure for Cortexa applications.

The current implementation scope is a single library package with provider-neutral auth contracts, Google OAuth provider support, an in-memory storage adapter, service orchestration, typed auth errors, build configuration, and a Google usage example.

This guide is the repository navigation and code placement reference. For system responsibilities, architectural boundaries, design principles, ecosystem role, and architectural constraints, use /docs/ARCHITECTURE.md.

Repository Organization Overview

The repository is organized as a single-package TypeScript library, not a monorepo. It uses a layer-based source layout under src/:

• core/ contains provider-neutral contracts and helpers.
• providers/ contains provider-specific integrations.
• storage/ contains persistence contracts and package-owned storage implementations.
• services/ contains application-facing orchestration.
• errors/ contains shared auth error types.
• index.ts is the public package export surface.

Generated output is emitted to dist/ by the TypeScript compiler and is not the source of record.

High-Level Repository Tree

.
|-- docs/
|   |-- ARCHITECTURE.md
|   `-- REPOSITORY.md
|-- examples/
|   `-- google-auth.ts
|-- src/
|   |-- core/
|   |-- errors/
|   |-- providers/
|   |   `-- google/
|   |-- services/
|   |-- storage/
|   `-- index.ts
|-- dist/
|-- package.json
|-- package-lock.json
|-- tsconfig.json
|-- CONTRIBUTING.md
|-- CHANGELOG.md
|-- .gitignore
`-- .env

Notes:

• dist/ is build output and is ignored by Git.
• .env is local environment configuration and is ignored by Git.
• Some .js files are currently present under src/. New package source should be added as TypeScript files; dist/ remains the normal compiler output location.

Top-Level Directory Responsibilities

Area	Responsibility	What belongs there	What should not belong there	Relationships
src/	Package source of record.	TypeScript contracts, providers, storage adapters, services, errors, and public exports.	Build output, local secrets, consumer application code, deployment infrastructure.	Compiled by tsconfig.json; re-exported through src/index.ts; emitted to dist/.
src/core/	Provider-neutral auth model and helpers.	Shared auth account, session, provider, lookup types, and provider-neutral utility functions.	Provider SDK usage, storage engine logic, HTTP handlers, application user or tenant models.	Used by providers, storage, services, and public exports.
src/providers/	External auth provider integrations.	Provider folders such as google/ that implement the common provider contract.	Provider-neutral contracts, persistence backends, consumer business integrations.	May depend on provider SDK packages; should expose normalized core types.
src/storage/	Storage boundary and package-owned storage implementations.	AuthStorageAdapter and reusable adapters such as MemoryAuthStorage.	Application-specific database schemas, migrations, tenant ownership rules, secret management.	Used by AuthService; depends on core auth account and lookup types.
src/services/	In-process orchestration for the package API.	Provider-agnostic flows that compose providers and storage adapters.	Provider SDK calls, durable persistence implementation details, HTTP route handling.	Depends on core contracts, storage contracts, and auth errors.
src/errors/	Shared auth-specific error classes.	Base and specialized errors exported to consumers.	Provider SDK error types as public contracts unless normalized.	Used by services and providers; exported through src/index.ts.
examples/	Minimal runnable usage examples.	Small examples showing how consumers compose exported package APIs.	Production application code, integration test fixtures, documentation prose.	Imports from src through the package entrypoint and may use local .env values.
docs/	Long-lived repository documentation.	Architecture and repository navigation documents.	Generated API output, deployment secrets, implementation inventories.	/docs/ARCHITECTURE.md covers architecture; this file covers repository navigation.
dist/	Compiler output.	JavaScript and declaration files emitted from src/.	Manual source edits or new feature implementation.	Referenced by package.json as package main and types; regenerated by npm run build.
Root package files	Package, TypeScript, npm, and local repository configuration.	package.json, package-lock.json, tsconfig.json, .gitignore, empty or supporting root docs.	Source modules that belong under src/.	Configure package metadata, dependencies, scripts, compiler output, and ignored files.

Modules and Package Organization

Module	Purpose	Responsibility	Reusability level	Dependency relationships
src/index.ts	Public package entrypoint.	Re-export consumer-facing contracts, classes, constants, and helpers.	Public API surface.	Depends on internal modules only through exports. Consumers should prefer this entrypoint.
src/core/	Core auth contracts.	Define provider names, account records, sessions, account lookup values, provider contract, and expiration helper.	Shared across the whole package.	Should remain provider-neutral and storage-neutral.
src/providers/google/	Google OAuth adapter.	Create Google OAuth clients, validate Google config, generate auth URLs, exchange codes, refresh tokens, define Google scopes.	Provider-specific reusable adapter.	Depends on googleapis, core contracts, and auth errors. Should not be imported by core modules.
src/storage/auth-storage-adapter.ts	Persistence port.	Define the storage methods required by the service layer.	Shared contract for package and consumer adapters.	Depends on core account and lookup types.
src/storage/memory-auth-storage.ts	Volatile storage adapter.	Store auth accounts in a process-local Map.	Reusable for local, test, or non-durable scenarios.	Implements AuthStorageAdapter; depends on core types.
src/services/auth-service.ts	Auth orchestration service.	Connect accounts, retrieve accounts, produce valid sessions, refresh expired credentials, and disconnect accounts.	Main application-facing service.	Depends on provider and storage interfaces, core helpers, and typed errors.
src/errors/	Error hierarchy.	Provide auth-specific errors for configuration, provider, and missing-account failures.	Shared public error types.	Base AuthError is extended by specialized auth errors.
examples/google-auth.ts	Google auth URL example.	Demonstrate constructing GoogleAuthProvider with environment-backed config and scope presets.	Example only.	Imports public exports from ../src and uses dotenv/config.

Dependency and Boundary Rules

• Core modules must remain provider-neutral and storage-neutral.
• Provider SDK dependencies belong under provider-specific folders such as src/providers/google/.
• Storage contracts belong in src/storage/; consumer-owned database details should not be introduced into core or service modules.
• AuthService should depend on the AuthProvider and AuthStorageAdapter contracts instead of concrete providers or storage engines.
• Public exports should be added to src/index.ts when they are intended for package consumers.
• dist/ should be treated as generated output. Edit src/ and rebuild instead of editing dist/.
• .env should remain local runtime configuration and must not become package source or documentation content.
• Examples may use environment variables and package exports, but they should not become the implementation location for reusable behavior.
• Root-level package and compiler configuration should remain focused on building and publishing the library package.

Current dependency direction:

src/index.ts
  -> src/core/
  -> src/providers/google/
  -> src/storage/
  -> src/services/
  -> src/errors/

src/services/
  -> src/core/
  -> src/storage/
  -> src/errors/

src/providers/google/
  -> src/core/
  -> src/errors/
  -> googleapis

src/storage/
  -> src/core/

Shared vs Implementation-Specific Components

Category	Current location	Guidance
Shared contracts	src/core/, src/storage/auth-storage-adapter.ts	Keep provider-neutral and reusable by package consumers.
Shared infrastructure	src/services/auth-service.ts, src/errors/	Keep orchestration and error behavior independent of concrete application runtimes.
Shared libraries	Public exports from src/index.ts	Export only stable package-facing APIs.
Runtime applications	None in the package.	Application runtimes, HTTP servers, and callback routes belong outside this repository.
Business or domain logic	src/core/ only for external auth account/session concepts.	Application user, tenant, authorization, and product logic belong outside this package.
Presentation layers	None.	UI components and browser screens do not belong in this repository.
Integrations	src/providers/google/	Add provider-specific code inside provider folders and normalize outputs to core types.
Experimental areas	None observed.	Do not add experimental folders without an explicit repository convention.
Generated output	dist/	Regenerate from TypeScript source. Do not use as the source of record.

Code Placement Guidance

Use these placement rules for common changes:

Change type	Add or modify code here	Additional steps
New provider-neutral type or helper	src/core/	Export from src/index.ts if it is part of the public package API.
New external auth provider	src/providers/<provider>/	Implement AuthProvider, add provider name support in src/core/auth-provider.ts, and export public classes or constants from src/index.ts.
New Google-specific behavior	src/providers/google/	Keep googleapis usage in this folder and return core auth types to callers.
New storage adapter contract method	src/storage/auth-storage-adapter.ts	Update AuthService, package-owned adapters, generated declarations through build, and any examples that depend on the contract.
New reusable storage adapter	src/storage/	Implement AuthStorageAdapter; keep database-specific configuration out of core modules.
Consumer-specific persistence	Consumer application repository.	Implement AuthStorageAdapter outside this package unless the adapter is intended to be reusable package infrastructure.
New service-level flow	src/services/auth-service.ts	Keep the flow provider-agnostic and storage-interface-based.
New auth error	src/errors/	Extend AuthError and export it from src/index.ts when consumer-facing.
New public API export	src/index.ts	Export from the source module rather than from dist/.
New usage example	examples/	Keep examples small and focused on composing exported APIs.
New repository documentation	docs/	Reference /docs/ARCHITECTURE.md for architecture instead of duplicating it.
Build output update	dist/ via npm run build	Do not edit generated files manually.
Tests	No test directory convention exists yet.	Introduce a test location intentionally as part of the testing change.

Repository Conventions

Observed conventions in the current implementation:

• The package is named @cortexa/auth.
• The package is built with TypeScript using src/ as rootDir and dist/ as outDir.
• package.json points package runtime output to dist/index.js and type declarations to dist/index.d.ts.
• The source entrypoint is src/index.ts; it re-exports the consumer-facing API.
• Source file names use lowercase kebab-case, such as auth-service.ts and google-provider.ts.
• TypeScript classes and interfaces use PascalCase, such as AuthService, AuthProvider, and GoogleAuthConfig.
• Constants use uppercase names, such as GOOGLE_SCOPES and GOOGLE_SCOPE_PRESETS.
• Provider-specific modules are grouped under src/providers/<provider>/.
• Error classes extend AuthError and set a specific name.
• Provider and storage operations are asynchronous and return Promise values.
• Internal imports use relative paths; no path aliases are configured.
• node_modules/, dist/, .env, logs, IDE files, OS files, and TypeScript build info are ignored by .gitignore.
• CONTRIBUTING.md and CHANGELOG.md exist at the repository root but are currently empty.

Documentation Corpus Map

Current documentation state:

• /docs/ARCHITECTURE.md: architectural entrypoint. Use it for system responsibilities, architectural boundaries, design principles, ecosystem role, architectural constraints, and design intent.
• /docs/REPOSITORY.md: this repository navigation and code organization guide.
• README.md: expected by the standard documentation corpus, but not present in the current repository tree.
• CONTRIBUTING.md: present at the repository root, currently empty.
• CHANGELOG.md: present at the repository root, currently empty.

This document should not duplicate /docs/ARCHITECTURE.md. Update this file when folders, modules, package boundaries, code placement conventions, or repository organization change.

Guidance for Developers and AI Agents

Start repository orientation with these files:

1. package.json for package identity, scripts, dependencies, and published output paths.
2. tsconfig.json for source and build output boundaries.
3. src/index.ts for the public API surface.
4. src/core/ for provider-neutral contracts.
5. /docs/ARCHITECTURE.md for architectural responsibilities and constraints.
6. This file for repository navigation and code placement.

When extending the repository:

• Identify the target layer before editing: core contract, provider adapter, storage adapter, service orchestration, error type, example, or documentation.
• Prefer adding behavior to the narrowest existing module that owns it.
• Keep provider-specific SDK usage out of src/core/, src/storage/, and src/services/.
• Keep consumer-owned application concerns out of this package.
• Add consumer-facing exports through src/index.ts.
• Treat src/ TypeScript files as source of record.
• Treat dist/ as generated output.
• Do not read or document local .env values.
• Use /docs/ARCHITECTURE.md for architecture questions instead of inferring architecture from folder names alone.
• If a requested change requires a new convention, make that convention explicit in code organization or documentation as part of the change.