Organizations & Vaults
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Organizations and Vaults form the core multi-tenancy and data isolation architecture of KnowledgeVault. Organizations serve as high-level entities that group users and resources, while Vaults act as isolated containers for documents, memories, and chat sessions. This structure allows for secure management of technical documentation across different teams or projects while maintaining strict access controls.
The system supports a hierarchical relationship where an Organization can contain multiple Vaults and Groups. Access to these resources is governed by a robust Role-Based Access Control (RBAC) system, ensuring that members, admins, and superadmins have appropriate levels of visibility and interaction within their designated environments.
Sources: README.md:15-35, backend/app/models/database.py:165-200
Data Model & Relationships
The underlying architecture relies on a relational schema that links users to organizations and subsequently to vaults through various membership and access tables.
Entity Relationships
The following diagram illustrates the primary relationships between Users, Organizations, and Vaults:
The system manages multi-tenancy by associating Vaults with specific org_id values and controlling user access via org_members, group_members, and vault_members tables.
Sources: backend/app/models/database.py:165-250
Core Data Structures
| Table | Primary Purpose | Key Fields |
|---|---|---|
organizations | High-level tenant entity | id, name, slug, created_by |
vaults | Data isolation container | id, name, org_id, visibility |
org_members | Links users to organizations | org_id, user_id, role (owner/admin/member) |
vault_members | Direct user-to-vault permissions | vault_id, user_id, permission (read/write/admin) |
vault_group_access | Group-based vault permissions | vault_id, group_id, permission |
Sources: backend/app/models/database.py:25-35, backend/app/models/database.py:178-250
Organization Management
Organizations are the primary unit of multi-tenancy. They are characterized by unique names and slugs, often used for routing or identification in the API.
Organization Roles
- Owner/Admin: Can manage organization members, update organization details, and create new vaults within the organization.
- Member: Standard user within the organization who can interact with resources they have been granted access to.
Sources: backend/app/models/database.py:192-200, frontend/src/lib/api.ts:685-700
API Operations
Organizations are managed through the /api/orgs/ endpoints. Operations include listing organizations, creating new entities, and managing membership.
Sources: frontend/src/lib/api.ts:685-705, README.md:315-325
Vault Architecture
Vaults are the fundamental unit of storage in KnowledgeVault. Every document, chunk, and memory is strictly scoped to a specific vault_id.
Vault Scope and Isolation
Vaults ensure that data from one project or client remains invisible to others. The database schema enforces this through vault_id columns in the following tables:
files: Document metadata and processing status.memories: Stored knowledge chunks and embeddings.chat_sessions: Conversation history.wiki_pages&kms_entries: Structured knowledge base entries.
Sources: backend/app/models/database.py:40-60, backend/app/models/database.py:100-130, backend/app/models/database.py:265-280
Access Control Logic
The backend utilizes a policy evaluation system to determine if a user can access a specific vault.
This logic ensures that access is checked against direct membership, group membership, and organization-wide visibility settings.
Sources: backend/app/api/routes/wiki.py:55-70, backend/app/models/database.py:25-35, backend/app/models/database.py:225-250
Storage & Filesystem
Vault data is persisted both in the SQLite database and on the filesystem. The system uses a specific directory structure for file uploads:
data/knowledgevault/vaults/
├── {vault_id}/
│ └── uploads/
│ ├── document1.pdf
│ └── document2.docx
On startup, a migration process (migrate_vault_paths) ensures that any legacy flat upload structures are moved into these numeric ID-based vault directories.
Sources: backend/app/models/database.py:445-485, README.md:210-225
Conclusion
The Organizations and Vaults system provides the necessary infrastructure for scalable, multi-tenant knowledge management. By combining filesystem isolation with a multi-layered RBAC database schema, KnowledgeVault allows organizations to maintain high-fidelity data boundaries while enabling collaborative AI-driven document interaction.
Sources: README.md:15-50, backend/app/models/database.py:25-35