Organizations, Teams, and Projects

Introduction to Organizational Hierarchy

Hopsule is designed to mirror the complex, multi-layered nature of modern engineering organizations. Unlike traditional tools that treat project structure as a simple file hierarchy, Hopsule treats your structure as a governance framework for decision-making and context preservation. By organizing your work into Organizations, Teams, and Projects, you create a clear lineage of authority and remembrance that scales from individual contributors to global enterprises.

The hierarchy in Hopsule follows a strict descending order: Organization → Teams → Projects. Each layer serves a specific purpose in the decision-making lifecycle. The Organization manages global identity and security, Teams manage functional domains and member groupings, and Projects serve as the primary containers for enforceable Decisions and append-only Memories. Understanding this structure is essential for ensuring that context remains portable and that enforcement is consistent across your entire engineering ecosystem.

Managing Organizations

The Organization is the highest-level entity in Hopsule. It represents the legal and administrative boundary for your engineering collective. All billing, global security configurations, and high-level audit trails are managed at the organization level. In Hopsule, an organization acts as the root of trust for the Knowledge Graph, ensuring that all preserved context is cryptographically secured and accessible only to authorized members.

When you first create an account on the Hopsule Dashboard, you are prompted to either join an existing organization via a secure invitation or create a new one. Creating an organization establishes you as the initial Owner, granting you full authority over member management, security policies, and the lifecycle of all underlying teams and projects. Because Hopsule prioritizes data sovereignty, every organization is isolated at the encryption layer, ensuring that your decisions and memories remain private and secure.

Creating and Configuring an Organization

1. Navigate to the Hopsule Dashboard and click on the organization selector in the top-left corner.

2. Select Create New Organization from the dropdown menu.

3. Enter your Organization Name and an optional Identifier. The identifier is used in the Hopsule CLI and Hopsule API to reference your organization programmatically.

4. Choose your encryption preference. While all plans include end-to-end encryption, Enterprise users may configure custom key management parameters during this stage.

5. Click Initialize Organization to finalize the setup.

Important: Organization names can be changed later, but the unique Identifier is permanent once the organization is initialized. This identifier is used by Hopper and the Hopsule CLI to maintain context-awareness across different environments.

Inviting and Managing Members

Collaboration is central to the Hopsule philosophy. To invite members to your organization, navigate to the Settings tab within the Hopsule Dashboard and select Members. Hopsule uses a secure, token-based invitation system to ensure that only authorized personnel can access your team's decision history. Invitations can be sent via email or generated as secure, one-time-use links.

When a member joins, they are assigned a global role within the organization. These roles define their baseline permissions across all teams and projects. However, Hopsule also supports granular overrides at the team and project levels, allowing for flexible governance models where a senior developer might be an Admin in a specific project but a Member at the organizational level.

Defining Teams within Organizations

Teams are logical groupings within an organization that represent functional units, such as "Platform Engineering," "Mobile Development," or "Security Operations." Teams serve as the primary bridge between the broad organizational policies and the specific execution of projects. They allow for the categorization of expertise and the focused preservation of context within a specific domain.

A team owns a collection of projects and provides a shared space for Context Packs (Capsules) that are relevant to that team's specific focus. For example, a "Frontend Team" might maintain a "UI Standards Capsule" that is automatically inherited by every project created under that team. This ensures that enforcement is a form of remembrance—reminding developers of the team's shared commitments without requiring manual oversight.

Creating a Team

1. From the Hopsule Dashboard, select your organization.

2. Navigate to the Teams section and click New Team.

3. Provide a Team Name and a description that outlines the team's functional responsibility.

4. Select the initial members from the organization's member pool.

5. Assign a Team Lead who will have administrative authority over all projects created within this team.

Tip: Use teams to mirror your actual organizational chart. This makes it easier for Hopper to suggest relevant decisions based on the functional context of the user's current work.

Project Management and Execution

Projects are the most granular level of the Hopsule hierarchy and where the day-to-day work of decision-making and context preservation happens. A project is a specific container for Decisions and Memories related to a codebase, a service, or a specific initiative. It is at the project level that Hopsule for VS Code enforces accepted decisions, providing real-time warnings when code contradicts the team's agreed-upon constraints.

Every project in Hopsule is designed to be self-documenting. As decisions move from Draft to Accepted, they build a living history of the project's evolution. When linked with Memories, these decisions provide a complete picture of why certain paths were taken, preventing the "organizational amnesia" that often plagues fast-moving engineering teams.

Project Settings and Customization

Within the Project Settings in the Hopsule Dashboard, you can configure several key parameters that define how Hopsule interacts with your development workflow:

• Default Tags: Define tags that are automatically applied to new Decisions and Memories created within the project. This improves searchability in the Knowledge Graph.

• Notification Preferences: Configure how the team receives updates on decision lifecycle changes. Notifications can be sent via the dashboard, email, or integrated webhooks via the Hopsule API.

• Enforcement Level: Determine how strictly Hopsule for VS Code should flag contradictions. You can choose between "Advisory" (warnings only) and "Strict" (requires explicit override documentation).

• Public Sharing: Generate secure tokens for read-only access to specific project decisions, useful for sharing context with external stakeholders or auditors.

Role Inheritance and Permissions

Hopsule utilizes a hierarchical permission model designed for both security and flexibility. Permissions flow downward from the Organization to the Project, but can be refined at each level. This ensures that governance is maintained while allowing individual project leads the autonomy they need to manage their specific domains.

Important: Role inheritance ensures that an Organization Owner always has visibility into the Knowledge Graph of every project. This is critical for maintaining an audit trail and ensuring that organizational judgment is preserved even as individual team members move between projects.

Cross-Project Governance and Portability

One of the unique strengths of Hopsule is its ability to share context across project boundaries. This is achieved through Context Packs (also known as Capsules). A Capsule is a portable bundle of Decisions and Memories that can be "installed" into multiple projects. For example, an organization might have a "Security Hardening Capsule" that contains all decisions regarding encryption standards and authentication protocols.

When a Capsule is active in a project, all decisions within that capsule are treated as enforceable constraints by Hopsule for VS Code and Hopsule CLI. This allows engineering leaders to enforce global standards without manually duplicating documentation across dozens of repositories. Furthermore, the Knowledge Graph (or Brain) provides a visual representation of how these decisions interact across different projects, highlighting potential conflicts or areas where context is missing.

The Knowledge Graph (Brain)

The Brain is a powerful visualization tool available in the Hopsule Dashboard. It maps the relationships between Organizations, Teams, Projects, Decisions, and Memories. By visualizing these links, engineering leaders can identify "decision hotspots" or see how a single deprecated decision in a shared Capsule might impact multiple downstream projects. This bird's-eye view is essential for large-scale governance and architectural oversight.

Lifecycle Management: Transferring, Archiving, and Deletion

As organizations evolve, projects may change ownership or reach their natural end-of-life. Hopsule provides robust tools for managing these transitions while ensuring that the underlying context is never lost. Because Hopsule's philosophy is that "Organizations forget; Hopsule remembers," we treat the archival of a project as a preservation event rather than a deletion event.

Transferring Projects

If a project moves from one functional area to another, an Admin can transfer the project between teams within the same organization. This process preserves all history, including the full version history of Decisions and the append-only log of Memories. To transfer a project, go to Project Settings → Danger Zone → Transfer Project and select the target team.

Archiving vs. Deleting

Hopsule strongly encourages Archiving over Deleting. When a project is archived:

• All Decisions and Memories are moved to a read-only state.

• The project is removed from active views in Hopsule for VS Code and the Hopsule CLI.

• The context remains searchable in the Hopsule Dashboard and visible in the Knowledge Graph.

• Hopper can still reference archived decisions when explaining the history of the organization.

Deletion is a permanent action that removes all data and breaks all links in the Knowledge Graph. Deletion is only recommended for projects created in error or containing sensitive information that must be purged for compliance reasons. Due to our commitment to security, deleted data is cryptographically wiped and cannot be recovered.

Multi-Organization Support

For consultants, agency developers, or leaders overseeing multiple distinct entities, Hopsule offers seamless multi-organization support. You can be a member of multiple organizations using a single identity. Switching between organizations in the Hopsule Dashboard or the Hopsule CLI instantly updates your context, ensuring that Hopper and the IDE Extension are always referencing the correct decision and memory layer for your current task.

To switch organizations in the Hopsule CLI, use the command hopsule auth switch. In the Hopsule Dashboard, simply use the organization selector in the top-left navigation bar. Each organization maintains its own isolated Knowledge Graph, ensuring that context from one client or entity never leaks into another, maintaining the highest standards of professional governance and data preservation.

Tip: If you are a solo developer, you can create a personal organization to preserve your own architectural decisions and memories. Hopsule treats solo mode as a first-class experience, allowing you to build a personal "Brain" of engineering judgment that follows you throughout your career.