Building Block #15: Team Communication Feed

Status: 📋 Planned Dependencies: Building Block #11 (Employee Management), Building Block #13 (Document Management for GCS) When: Month 5 (ADD-ON Phase) Context: Solo Developer + AI

Definition

Implement Instagram-style social feed for company communication with:

• Posts (text + images)
• Likes and comments (flat, not nested)
• Company/department/team visibility
• AI-generated post summaries
• @mentions and notifications
• Media upload to Google Cloud Storage

Dependencies

• ✅ Building Block #11: Employee Management
  • Employee model exists
  • Team and Department relationships established
• ✅ Building Block #13: Document Management
  • GCS integration available for media uploads
• Requires existing foundation patterns

Implementation Checklist

GATE 1: BUILD

Database Models

• Create TeamPost model
  • id (UUID)
  • tenantId
  • authorId (employeeId)
  • content (text, max 2000 chars)
  • visibility (COMPANY, DEPARTMENT, TEAM, PRIVATE)
  • departmentId (optional, for DEPARTMENT visibility)
  • teamId (optional, for TEAM visibility)
  • mediaUrls (String[] - GCS URLs)
  • aiSummary (optional, AI-generated)
  • isPinned (boolean)
  • likeCount (denormalized)
  • commentCount (denormalized)
  • createdAt, updatedAt
• Create PostLike model
  • id (UUID)
  • postId
  • employeeId
  • createdAt
  • @@unique([postId, employeeId])
• Create PostComment model
  • id (UUID)
  • tenantId
  • postId
  • authorId (employeeId)
  • content (text, max 500 chars)
  • createdAt, updatedAt
• Create PostMention model
  • id (UUID)
  • postId
  • commentId (optional, if mention is in comment)
  • mentionedEmployeeId
  • createdAt
• Create Notification model (if not exists)
  • id (UUID)
  • tenantId
  • recipientId (employeeId)
  • type (POST_MENTION, COMMENT_MENTION, POST_LIKE, POST_COMMENT)
  • referenceType (POST, COMMENT)
  • referenceId
  • isRead (boolean)
  • createdAt
• Add relationships
  • TeamPost ↔ Employee (author, many-to-one)
  • TeamPost ↔ Department (optional, many-to-one)
  • TeamPost ↔ Team (optional, many-to-one)
  • PostLike ↔ TeamPost, Employee
  • PostComment ↔ TeamPost, Employee
  • PostMention ↔ TeamPost, PostComment, Employee
• Create migration
• Add indexes
  • TeamPost(tenantId, createdAt DESC)
  • TeamPost(tenantId, visibility, departmentId)
  • TeamPost(tenantId, visibility, teamId)
  • PostLike(postId, employeeId)
  • PostComment(postId, createdAt)
  • Notification(recipientId, isRead, createdAt)

Backend Implementation

• Create TeamFeedModule
• Create TeamPostRepository (with tenant + visibility filtering)
• Create TeamPostController
  • GET /api/v1/feed (list posts with visibility filtering)
  • GET /api/v1/feed/:id (get single post with comments)
  • POST /api/v1/feed (create post)
  • PUT /api/v1/feed/:id (update own post)
  • DELETE /api/v1/feed/:id (delete own post or admin)
  • POST /api/v1/feed/:id/like (like post)
  • DELETE /api/v1/feed/:id/like (unlike post)
  • POST /api/v1/feed/:id/comments (add comment)
  • DELETE /api/v1/feed/:id/comments/:commentId (delete comment)
  • POST /api/v1/feed/:id/pin (pin post - admin only)
  • DELETE /api/v1/feed/:id/pin (unpin post)
• Create PostService with:
  • Visibility-based feed filtering
  • Denormalized counter updates (likes, comments) with transactions
  • @mention parsing and notification creation
  • AI summary generation (call AI service)
• Create MediaUploadService
  • Upload images to GCS
  • Generate signed URLs for display
  • Image validation (type, size limit)
• Create NotificationService
  • Create notifications for mentions, likes, comments
  • Mark as read
  • GET /api/v1/notifications (list)
  • PUT /api/v1/notifications/:id/read (mark read)
  • PUT /api/v1/notifications/read-all (mark all read)
• Add DTOs with validation
  • CreatePostDto (content, visibility, mediaFiles)
  • CreateCommentDto (content)
  • PostResponseDto (with author, likes, comments)
• Add permission checks (feed:read, feed:create, feed:moderate)

AI Integration

• Implement AI summary generation
  • Call AI service to summarize long posts
  • Store summary in aiSummary field
  • Trigger on post creation (async via BullMQ if available)
• Optional: AI-powered content moderation
  • Flag potentially inappropriate content

Frontend Implementation

• Create feed page (infinite scroll)
• Create post card component
• Create post creation form (with image upload)
• Create like button component (optimistic updates)
• Create comment section component
• Create @mention autocomplete component
• Create notification bell component
• Create notification dropdown/page
• Add visibility selector in post form
• Add pinned posts section at top
• Add loading states and error handling

GATE 2: TEST

• Test post CRUD operations
• Test visibility filtering (company, department, team)
• Test like/unlike with counter updates
• Test comment CRUD
• Test @mention parsing and notifications
• Test media upload to GCS
• Test AI summary generation
• Test denormalized counter consistency
• Test notification creation and delivery
• Test tenant isolation
• Test permission enforcement
• Write unit tests
• Write integration tests
• All tests passing

GATE 3: REVIEW & APPROVE

• Self-review implementation
• Verify visibility filtering works correctly
• Check denormalized counters stay in sync
• Verify GCS integration for media
• Test AI summary quality
• Document approval reasoning
• Status: ✅ APPROVED

GATE 4: DOCUMENT

• Document team feed architecture
• Document visibility model
• Document @mention system
• Document notification system
• Document AI summary integration
• Update API documentation
• Update .cursorrules
• Update CLAUDE.md
• Update memory log

GATE 5: COMMIT & TAG

• Git commit with clear message: "Building Block #15: Team Communication Feed complete"
• Tag: building-block-15-team-feed
• Push to main
• Update status tracker

Testing Requirements

Unit Tests

• Post visibility filtering logic
• @mention parsing
• Denormalized counter updates
• Notification creation logic

Integration Tests

• Post creation with media upload
• Like/unlike flow
• Comment flow
• Notification delivery
• Feed filtering by visibility
• Tenant isolation

Documentation Requirements

• Team feed architecture
• Visibility model documentation
• @mention and notification system
• AI summary integration
• API endpoint documentation
• Frontend component guide

Approval Criteria

Building block is complete when:

• ✅ Post CRUD working
• ✅ Visibility filtering working (company, department, team)
• ✅ Like/unlike working with counter sync
• ✅ Comments working
• ✅ @mentions working with notifications
• ✅ Media upload to GCS working
• ✅ AI summaries generating
• ✅ Notifications working
• ✅ All tests passing
• ✅ Documentation complete

AI Context

What AI needs to know:

• Posts have visibility: COMPANY, DEPARTMENT, TEAM, PRIVATE
• Feed filtering: Show posts where user has access based on visibility
  • COMPANY: All posts in tenant
  • DEPARTMENT: Posts in user's department(s)
  • TEAM: Posts in user's team(s)
  • PRIVATE: Only author's own posts
• Use denormalized counters (likeCount, commentCount) with transactional updates
• @mention format: @[Employee Name](employeeId)
• Media stored in GCS, URLs in mediaUrls array
• AI summary triggered async on post creation

Patterns to follow:

• Repository methods filter by tenantId AND visibility
• Use @RequirePermissions('feed:read') decorator
• Denormalized counters updated in same transaction as like/comment
• Notifications created via NotificationService
• Media upload uses same GCS integration as Document Management
• AI summary via AI Service (Building Block #07)

Simplified Design Choices

Based on feature-phases.mdx guidance:

• ✅ Text posts + images only (no video/voice)
• ✅ Flat comments (no nested threads)
• ✅ Simple AI summaries
• ❌ No complex notification system (just in-app)
• ❌ No real-time updates (polling or manual refresh)

Next Building Block

After completion, proceed to Building Block #16: Goals / OKR Tracking

---

Last Updated: 2025-11-27