Skip to content

Package Overview

The CyberEco data layer is split into 4 npm packages designed around a clean dependency graph, constructor injection, and backend portability via the StorageAdapter pattern.

Dependency Graph

graph TD
    types["@cyber-eco/types<br/><small>Pure TypeScript interfaces</small>"]
    firebase["@cyber-eco/firebase<br/><small>Firebase StorageAdapter</small>"]
    auth["@cyber-eco/auth<br/><small>Auth, SSO, JWT, permissions</small>"]
    services["@cyber-eco/services<br/><small>DataLayerService + domain services</small>"]
    hub["apps/hub<br/><small>Astro + React islands</small>"]

    types --> firebase
    types --> auth
    types --> services
    auth --> services
    firebase --> hub
    services --> hub
    auth --> hub

    style types fill:#4db6ac,color:#000
    style firebase fill:#ff8a65,color:#000
    style auth fill:#ba68c8,color:#000
    style services fill:#64b5f6,color:#000
    style hub fill:#ffd54f,color:#000

Packages

Package Description Runtime Deps Peer Deps
@cyber-eco/types TypeScript interfaces, constants, and type utilities. Zero runtime dependencies. None None
@cyber-eco/firebase FirebaseStorageAdapter implementing the StorageAdapter interface. Firestore helpers and auth operations. @cyber-eco/types firebase >=11.0.0
@cyber-eco/auth Authentication, SSO, permissions, JWT, rate limiting, error recovery. Dual entry points for client and server. @cyber-eco/types, zod firebase >=11.0.0, react >=18.0.0 (optional), jsonwebtoken >=9.0.0 (optional)
@cyber-eco/services DataLayerService orchestrator and domain services. Zero Firebase imports -- all data access via StorageAdapter. @cyber-eco/types, @cyber-eco/auth None

Key Design Principles

StorageAdapter Abstraction

All domain services operate through the StorageAdapter interface, never directly through Firebase. This enables testing with MockStorageAdapter and future migration to IPFS, blockchain, or any other backend.

Critical Constraint

@cyber-eco/services must have zero imports from firebase/*. This is verified with: 

grep -r "firebase" packages/services/src/
# Expected: zero results

Build Order

Packages build in topological order via Turborepo:

@cyber-eco/types          (no deps -- builds first)
       |
       +------------------+
       |                  |
@cyber-eco/firebase   @cyber-eco/auth       (can build in parallel)
       |                  |
       +--------+---------+
                |
        @cyber-eco/services               (builds last)

All packages use tsup for dual ESM/CJS output with TypeScript declarations.

Quick Start

# Install all workspace dependencies
npm ci

# Build all packages (topological order)
npm run build

# Run all tests
npm run test

# Type-check everything
npm run type-check

Versioning

All 4 packages share the same version number via Changesets with fixed versioning. When any package changes, all packages are released together.

Package Guides