Knowledge

Overview

The Knowledge Hub is a comprehensive internal knowledge management system featuring hierarchical organization through sections and categories, collaborative commenting, revision history, bookmarking, and audience-based access control. It enables teams to create, organize, and share knowledge articles with rich content support.

Key Features

Hierarchical Organization

• Sections: Top-level organizational units
• Categories: Second-level grouping within sections
• Posts: Individual knowledge articles
• Nested Structure: Sections → Categories → Posts

Content Management

• Rich Text Content: Full markdown and HTML support
• Post Metadata: Title, slug, description, cover images
• Draft/Published States: Control article visibility
• Author Attribution: Track article creators
• Featured Posts: Highlight important articles
• Reading Time: Automatic calculation

Collaborative Features

• Comments: User comments on knowledge posts
• Accepted Answers: Mark helpful comments as accepted
• Revision History: Track all post changes
• Content Versioning: Store previous versions
• Bookmarks: Users can bookmark favorite articles

Tagging System

• Multi-tag Support: Assign multiple tags per post
• Color-Coded Tags: Visual tag identification
• Tag-Based Filtering: Find posts by tags
• Tag Management: Admin controls for tag creation

Access Control

• Audience-Based Visibility: Show posts to specific user groups
• Creator Permissions: Original authors maintain control
• Public vs Private: Control article visibility
• Section-Level Access: Restrict entire sections

Database Models

KnowledgeHubPost Model

model KnowledgeHubPost {
  id              String                    @id @default(cuid())
  createdAt       DateTime                  @default(now())
  updatedAt       DateTime                  @updatedAt
  tenantId        String
  tenant          Tenant                    @relation(fields: [tenantId], references: [id])
  createdByUserId String?
  createdByUser   User?                     @relation(fields: [createdByUserId], references: [id])
  categoryId      String
  category        KnowledgeHubCategory      @relation(fields: [categoryId], references: [id])
  slug            String
  title           String
  description     String
  content         String                    @db.NVarChar(max)
  coverImage      String?
  readingTime     String?
  isPublished     Boolean                   @default(false)
  isFeatured      Boolean                   @default(false)
  comments        KnowledgeHubPostComment[]
  revisions       KnowledgeHubPostRevision[]
  postTags        KnowledgeHubPostTag[]
  bookmarks       KnowledgeHubBookmark[]
  audience        Audience[]

  @@unique([tenantId, slug])
}

KnowledgeHubCategory Model

model KnowledgeHubCategory {
  id        String             @id @default(cuid())
  createdAt DateTime           @default(now())
  updatedAt DateTime           @updatedAt
  tenantId  String
  tenant    Tenant             @relation(fields: [tenantId], references: [id])
  sectionId String
  section   KnowledgeHubSection @relation(fields: [sectionId], references: [id])
  name      String
  slug      String
  icon      String?
  color     String?
  type      String             @default("article")
  posts     KnowledgeHubPost[]

  @@unique([tenantId, slug])
}

KnowledgeHubSection Model

model KnowledgeHubSection {
  id         String                 @id @default(cuid())
  createdAt  DateTime               @default(now())
  updatedAt  DateTime               @updatedAt
  tenantId   String
  tenant     Tenant                 @relation(fields: [tenantId], references: [id])
  name       String
  slug       String
  icon       String?
  color      String?
  order      Int                    @default(0)
  categories KnowledgeHubCategory[]

  @@unique([tenantId, slug])
}

KnowledgeHubPostComment Model

model KnowledgeHubPostComment {
  id              String           @id @default(cuid())
  createdAt       DateTime         @default(now())
  updatedAt       DateTime         @updatedAt
  postId          String
  post            KnowledgeHubPost @relation(fields: [postId], references: [id])
  createdByUserId String?
  createdByUser   User?            @relation(fields: [createdByUserId], references: [id])
  content         String           @db.NVarChar(max)
  isAccepted      Boolean          @default(false)
}

KnowledgeHubPostRevision Model

model KnowledgeHubPostRevision {
  id         String           @id @default(cuid())
  createdAt  DateTime         @default(now())
  postId     String
  post       KnowledgeHubPost @relation(fields: [postId], references: [id])
  userId     String?
  user       User?            @relation(fields: [userId], references: [id])
  title      String
  content    String           @db.NVarChar(max)
  changeNote String?
}

KnowledgeHubTag Model

model KnowledgeHubTag {
  id        String                @id @default(cuid())
  createdAt DateTime              @default(now())
  tenantId  String
  tenant    Tenant                @relation(fields: [tenantId], references: [id])
  name      String
  slug      String
  color     String?
  posts     KnowledgeHubPostTag[]

  @@unique([tenantId, slug])
}

KnowledgeHubBookmark Model

model KnowledgeHubBookmark {
  id        String           @id @default(cuid())
  createdAt DateTime         @default(now())
  userId    String
  user      User             @relation(fields: [userId], references: [id])
  postId    String
  post      KnowledgeHubPost @relation(fields: [postId], references: [id])

  @@unique([userId, postId])
}

Routes

User Routes

• /app/{tenant}/knowledge - Browse knowledge base
• /app/{tenant}/knowledge/{section} - View section
• /app/{tenant}/knowledge/{section}/{category} - View category
• /app/{tenant}/knowledge/{section}/{category}/{post} - View article

Admin Routes

• /app/{tenant}/settings/knowledge - Manage knowledge base
• /app/{tenant}/settings/knowledge/sections - Manage sections
• /app/{tenant}/settings/knowledge/categories - Manage categories
• /app/{tenant}/settings/knowledge/posts - Manage posts
• /app/{tenant}/settings/knowledge/posts/new - Create new post
• /app/{tenant}/settings/knowledge/posts/{id} - Edit post
• /app/{tenant}/settings/knowledge/tags - Manage tags

Content Organization

Section Structure

Sections are the top-level organizational units:

• Name and slug (unique per tenant)
• Icon and color for visual identification
• Order for custom sorting
• Contains multiple categories

Category Structure

Categories group related posts within a section:

• Belongs to one section
• Name, slug, icon, color
• Type (article, guide, tutorial, etc.)
• Contains multiple posts

Post Structure

Individual knowledge articles:

• Belongs to one category (and indirectly to a section)
• Unique slug per tenant
• Rich content with HTML/Markdown support
• Cover image, reading time
• Tags for cross-category organization
• Comments, revisions, bookmarks

Collaborative Features

Comments

Users can comment on knowledge posts:

• Rich text comments
• Author attribution
• Accepted answer marking (for Q&A style posts)
• Comment count tracking
• Nested discussions support

Revision History

Track all changes to knowledge posts:

• Stores previous versions of title and content
• User attribution for changes
• Optional change notes
• Timestamp tracking
• Full version history

Bookmarks

Users can bookmark posts for quick access:

• Personal bookmarks per user
• Quick access to saved articles
• Track popular/useful content

Access Control

Audience-Based Filtering

const posts = await getRecentKnowledgeHubPosts({
  tenantId,
  limit: 3,
  audienceUserId,
});

// Filtering logic:
// - No audience = public to all
// - Has audience = only visible to audience members
// - Creator can always see their own posts

Visibility Rules

Posts are visible when:

• isPublished is true
• User is in assigned audience, OR
• No audience assigned (public), OR
• User is the post creator

Best Practices

1. Hierarchical Planning: Design section and category structure before creating posts
2. Consistent Naming: Use clear, descriptive names for sections, categories, and posts
3. Tagging Strategy: Develop consistent tagging conventions
4. Content Quality: Write clear, concise articles with good formatting
5. Revision Notes: Always add change notes when updating posts
6. Audience Targeting: Use audiences to segment sensitive or department-specific content
7. Featured Posts: Highlight most important or frequently accessed articles
8. Comment Moderation: Regularly review and accept helpful comments

Common Operations

Create Knowledge Post

1. Navigate to /app/{tenant}/settings/knowledge/posts/new
2. Select category
3. Enter title (slug auto-generates)
4. Write description and content
5. Add cover image URL
6. Assign tags
7. Set publish status
8. Assign audiences
9. Save or publish

Manage Sections

1. Create logical top-level sections (e.g., "Getting Started", "Advanced Topics")
2. Assign icons and colors for visual distinction
3. Set order for navigation priority
4. Organize categories within sections

Comment on Post

1. View published knowledge post
2. Scroll to comments section
3. Write comment
4. Submit
5. Post author or admin can mark as accepted answer

Track Revisions

1. Edit existing post
2. Make changes to title or content
3. Add revision note explaining changes
4. Save
5. New revision automatically created with timestamp and user

Integration Points

• Audiences: Audience-based content visibility
• Users: Author attribution, comments, bookmarks
• Sections/Categories: Hierarchical content organization
• Tags: Cross-category content discovery
• Comments: Collaborative knowledge building
• Revisions: Content version control and audit trail
• Bookmarks: User-specific content curation