Package Scopes & Naming Conventions

This document defines the official Single Source of Truth (SSOT) for package naming conventions, NPM scoping standards, and registry governance across the tupynambalucas.dev monorepo.

Architectural Standard

The monorepo enforces a Hierarchical Bounded Context Scoping Standard. All packages are owned by the organizational enterprise scope @tupynambalucas-dev/, followed by a deterministic prefix indicating their architectural Bounded Context.

---

1. Enterprise Scope Hierarchy

The package naming taxonomy directly mirrors the domain topology of the ecosystem:

@tupynambalucas-dev/<context>-<project>
├── @tupynambalucas-dev/platform             # Root Monorepo Orchestrator
├── @tupynambalucas-dev/corporate-*          # Corporate Products & Documentation
├── @tupynambalucas-dev/cortex-*             # AI Subsystem & MCP Federation
├── @tupynambalucas-dev/studio-*             # Design System & Creative Assets
├── @tupynambalucas-dev/shared-*             # Cross-Cutting Foundations & SSOT
└── @tupynambalucas-dev/tools-*              # Automation CLI & Tooling

1.1 Root Package Identity

The root workspace is formally registered as:

• Package Identifier: @tupynambalucas-dev/platform
• GitHub Repository: tupynambalucas-dev/docs
• Classification: Internal Developer Platform (IDP) and task orchestrator.

The root package manages global dev engines (pnpm), orchestration pipelines (turbo), and unified lint/format configurations.

---

2. Monorepo Package Inventory

The monorepo contains 22 workspace packages organized into isolated Bounded Contexts:

A. Corporate Context (corporate/)

Houses public-facing digital products, commercial APIs, and knowledge base infrastructure.

Package Name	Physical Location	Classification	Responsibility
@tupynambalucas-dev/corporate-web	corporate/services/web	Application	React 19 showcase & e-commerce client.
@tupynambalucas-dev/corporate-api	corporate/services/api	Service	Fastify 5 REST API & transactional backend.
@tupynambalucas-dev/corporate-core	corporate/packages/core	Library	Shared domain entities, contracts, and Zod schemas.
@tupynambalucas-dev/corporate-portal	corporate/services/portal	Application	Docusaurus developer documentation portal.
@tupynambalucas-dev/corporate-collections	corporate/collections	Content Library	Decoupled documentation collections & translation sets.
@tupynambalucas-dev/corporate-preset	corporate/packages/preset	Plugin Library	Reusable Docusaurus preset with AST loaders & plugins.
@tupynambalucas-dev/corporate-theme	corporate/packages/theme	UI Library	Custom Docusaurus components, styling, and layouts.

B. Cortex Context (hub/cortex/)

Houses the AI cognitive engine, persistent vector memory, and Model Context Protocol (MCP) toolchains.

Package Name	Physical Location	Classification	Responsibility
@tupynambalucas-dev/cortex-memory-core	hub/cortex/memory/packages/core	Library	MongoDB Vector RAG schemas & graph algorithms.
@tupynambalucas-dev/cortex-memory-api	hub/cortex/memory/services/api	Service	Fastify memory ingestion & semantic search API.
@tupynambalucas-dev/cortex-memory-web	hub/cortex/memory/services/web	Application	Graph explorer and memory visualization dashboard.
@tupynambalucas-dev/cortex-mcp-guardrails	hub/cortex/mcp/guardrails	MCP Service	CEL security policy validator and prompt filter.
@tupynambalucas-dev/cortex-mcp-firecrawl	hub/cortex/mcp/services/firecrawl	MCP Adapter	Web scraping and content extraction gateway adapter.
@tupynambalucas-dev/cortex-mcp-memory	hub/cortex/mcp/services/memory	MCP Adapter	Native MCP tool server exposing semantic vector retrieval.

C. Studio Context (hub/studio/)

Houses design assets, brand identity tokens, and media distribution tooling.

Package Name	Physical Location	Classification	Responsibility
@tupynambalucas-dev/studio-assets	hub/studio/assets	Design Library	CSS design tokens, SVG logo marks, and typography.
@tupynambalucas-dev/studio-bucket	hub/studio/bucket	CLI Tool	Cloudflare R2 binary bucket synchronization utility.

D. Shared Foundation Context (shared/)

Houses repository-wide single-source-of-truth constants and developer lifecycle automation.

Package Name	Physical Location	Classification	Responsibility
@tupynambalucas-dev/shared-config	shared/config	Config Library	Prettier rules, TSConfig base, and project metadata.
@tupynambalucas-dev/shared-git	shared/git	Automation Library	Husky lifecycle hooks and commit message linters.

E. Tooling & Infrastructure Contexts (tools/, k8s/, renderer/)

Houses operational automation, profile rendering, and cloud delivery manifests.

Package Name	Physical Location	Classification	Responsibility
@tupynambalucas-dev/tools-provisioner	tools/provisioner	CLI Tool	Interactive scaffolding CLI for new workspaces and configs.
@tupynambalucas-dev/tools-github	tools/github	CLI Tool	Containerized GitHub automation and RBAC scripts.
@tupynambalucas-dev/renderer	renderer	Pipeline Tool	Dynamic GitHub SVG profile card and README compiler.
@tupynambalucas-dev/k8s	k8s	Manifest Suite	Multi-cluster Helm charts, Kustomize overlays, and Skaffold.

---

3. Workspace Dependency Protocol

All cross-package dependencies within the monorepo MUST declare the workspace:* protocol:

{
  "dependencies": {
    "@tupynambalucas-dev/corporate-core": "workspace:*",
    "@tupynambalucas-dev/studio-assets": "workspace:*"
  },
  "devDependencies": {
    "@tupynambalucas-dev/shared-config": "workspace:*"
  }
}

Semantic Version Replacement

When packages are packed or published, pnpm automatically substitutes the workspace:* wildcard with the exact resolved SemVer version of the target package.

---

4. Security & Registry Governance

The scoping architecture is explicitly designed to satisfy zero-trust supply-chain requirements:

4.1 Dependency Confusion Prevention

In public package registries, unscoped packages or generic scopes (such as @shared or @tools) are subject to Dependency Confusion attacks, where malicious actors claim the namespace on npmjs.com with inflated SemVer numbers.

• Mandatory Ownership: Every internal package resides under @tupynambalucas-dev/.
• Public Reservation: The organization scope @tupynambalucas-dev is claimed and verified on npmjs.com, precluding any external registration under the namespace.

4.2 GitHub Packages Registry Compliance

The GitHub Packages npm registry (npm.pkg.github.com) enforces a strict namespace constraint: the package scope must strictly equal the repository owner or organization name.

• Any attempt to publish @shared/config or @cortex/memory to GitHub Packages returns HTTP 403 Forbidden.
• Using @tupynambalucas-dev/<context>-<package> ensures 100% native compatibility with GitHub Packages publishing workflows without registry aliasing workarounds.

---

5. AI Agent Cognitive Routing

Autonomous coding agents (such as Antigravity, Gemini CLI, and Claude Code) operate under strict token window constraints.

The deterministic prefixing model accelerates agent reasoning:

1. Immediate Domain Inference: When an agent encounters import \{ schema \} from '@tupynambalucas-dev/cortex-memory-core', it deduces the target Bounded Context in a single token evaluation step.
2. Blast Radius Containment: Agents can be constrained via ESLint boundary rules to prevent unauthorized cross-boundary imports (e.g., forbidding @tupynambalucas-dev/corporate-web from importing internal adapters of @tupynambalucas-dev/cortex-mcp-guardrails).
3. Parity with Context Hierarchy: The package taxonomy aligns 1:1 with the 3-layer AGENTS.md context routing rules, allowing agents to locate authoritative rulesets predictably.