Repository docs from .qoder/repowiki

Anonymous Posting System

Referenced Files in This Document

• post.controller.ts
• post.service.ts
• post.schema.ts
• post.repo.ts
• post.adapter.ts
• post.table.ts
• moderator.service.ts
• post.cache-keys.ts
• post.ts
• moderation.ts
• moderation.ts (admin)
• postStore.ts
• useSocket.ts
• notification.service.ts

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document explains Flick’s anonymous posting system end-to-end. It covers the post creation workflow, content validation, topic assignment, privacy controls, anonymous posting mechanics, user identity obfuscation, content moderation integration, post lifecycle (creation to deletion), editing permissions and ownership verification, schema validation and request/response formats, error handling, real-time updates, trending algorithms, content discovery, filtering by topic/college/branch, and notification integration patterns.

Project Structure

The anonymous posting system spans three layers:

• Backend API and domain logic (server)
• Frontend API clients and UI stores (web)
• Admin moderation configuration (admin)

graph TB
subgraph "Server"
PC["PostController"]
PS["PostService"]
PR["PostRepo"]
PA["PostAdapter"]
PT["Post Table"]
MS["ModeratorService"]
CK["Post Cache Keys"]
end
subgraph "Web"
WA["postApi"]
WS["postStore"]
WM["moderation utility"]
end
subgraph "Admin"
AM["moderationApi"]
end
PC --> PS
PS --> PR
PR --> PA
PA --> PT
PS --> MS
PR --> CK
WA --> PC
WS --> WA
WM --> AM

Diagram sources

• post.controller.ts
• post.service.ts
• post.repo.ts
• post.adapter.ts
• post.table.ts
• moderator.service.ts
• post.cache-keys.ts
• post.ts
• postStore.ts
• moderation.ts
• moderation.ts (admin)

Section sources

• post.controller.ts
• post.service.ts
• post.schema.ts
• post.repo.ts
• post.adapter.ts
• post.table.ts
• moderator.service.ts
• post.cache-keys.ts
• post.ts
• postStore.ts
• moderation.ts
• moderation.ts (admin)

Core Components

• PostController: Exposes REST endpoints for creating, retrieving, updating, deleting posts, and filtering by topic/college/branch. It parses and validates requests using Zod schemas and delegates to PostService.
• PostService: Implements business logic including moderation checks, ownership verification, privacy enforcement, caching invalidation, and audit recording.
• PostRepo and PostAdapter: Encapsulate read/write operations to the database with caching and complex joins for enriched post data.
• ModeratorService: Integrates banned-word detection and Perspective API-based toxicity validation to enforce content policies.
• Web API and Utilities: Provide typed API clients and client-side moderation utilities for pre-submission validation and UI feedback.
• Admin Moderation API: Allows administrators to manage banned-word configurations consumed by the backend.

Section sources

• post.controller.ts
• post.service.ts
• post.schema.ts
• post.repo.ts
• post.adapter.ts
• moderator.service.ts
• post.ts
• moderation.ts
• moderation.ts (admin)

Architecture Overview

The system follows a layered architecture:

• Presentation: Web API clients and UI stores
• Application: Controllers and Services
• Persistence: Repositories and Adapters backed by PostgreSQL
• Moderation: Dynamic banned-word matcher and external validator

sequenceDiagram
participant Client as "Web Client"
participant API as "PostController"
participant Service as "PostService"
participant Repo as "PostRepo"
participant Adapter as "PostAdapter"
participant DB as "Postgres"
participant Mod as "ModeratorService"
Client->>API : POST /posts (title, content, topic, isPrivate)
API->>API : Parse & validate with CreatePostSchema
API->>Service : createPost({title, content, topic, isPrivate, postedBy})
Service->>Mod : moderateText(content + title)
Mod-->>Service : allowed=true/false
alt allowed
Service->>Repo : Write.create(...)
Repo->>Adapter : create(...)
Adapter->>DB : INSERT posts
DB-->>Adapter : new post
Adapter-->>Repo : post
Repo-->>Service : post
Service-->>API : post
API-->>Client : 201 Created
else not allowed
Service-->>API : HttpError (policy violation)
API-->>Client : 400 Bad Request
end

Diagram sources

• post.controller.ts
• post.service.ts
• post.schema.ts
• post.repo.ts
• post.adapter.ts
• moderator.service.ts

Detailed Component Analysis

Post Creation Workflow

• Validation: Zod schemas enforce length limits and topic enumeration for create/update operations.
• Moderation: Content is checked against banned words and contextual toxicity thresholds before persisting.
• Persistence: Post is inserted with metadata and ownership linked to the authenticated user.
• Caching: Post and list version keys are bumped to invalidate caches.

flowchart TD
Start([Create Post]) --> Validate["Parse & Validate Input"]
Validate --> Moderate["Moderate Text"]
Moderate --> Allowed{"Allowed?"}
Allowed --> |No| Error["Throw Policy Violation Error"]
Allowed --> |Yes| Persist["Persist to DB"]
Persist --> Audit["Record Audit"]
Audit --> Invalidate["Invalidate Cache Versions"]
Invalidate --> Return["Return Created Post"]
Error --> End([Exit])
Return --> End

Diagram sources

• post.schema.ts
• post.service.ts
• post.adapter.ts
• post.cache-keys.ts

Section sources

• post.controller.ts
• post.service.ts
• post.schema.ts
• post.adapter.ts
• post.cache-keys.ts

Content Validation and Topic Assignment

• Title/content length limits and topic enumeration are enforced by Zod schemas.
• Topic normalization supports exact match, case-insensitive match, and URL-decoded match for flexible client inputs.
• Privacy control: isPrivate toggles visibility rules based on user authentication and college association.

Section sources

• post.schema.ts
• post.schema.ts
• post.service.ts

Privacy Controls and Identity Obfuscation

• Private posts are visible only to authenticated users within the same college as the author.
• Unauthenticated users see only public posts.
• The system does not expose author identity beyond the author’s username, branch, and college metadata in enriched queries.

Section sources

• post.adapter.ts
• post.service.ts

Ownership Verification and Editing Permissions

• Update/Delete operations require the requesting user ID to match the post’s author ID.
• Unauthorized attempts are rejected with appropriate HTTP errors.

Section sources

• post.service.ts
• post.service.ts

Post Lifecycle: Retrieval, Filtering, and Discovery

• Retrieval: Fetch by ID with privacy checks, paginated lists with sorting and filtering, and counts for pagination metadata.
• Filtering: By topic, college, branch, author, and user context (including blocking relations).
• Discovery: Trending posts by view count.

sequenceDiagram
participant Client as "Web Client"
participant API as "PostController"
participant Service as "PostService"
participant Repo as "PostRepo"
participant Adapter as "PostAdapter"
Client->>API : GET /posts?page&limit&sortBy&sortOrder&topic&collegeId&branch
API->>API : Parse & validate query with GetPostsQuerySchema
API->>Service : getPosts({page, limit, sortBy, sortOrder, topic, collegeId, branch, userId, userCollegeId, blockerAuthId})
Service->>Repo : CachedRead.findMany(...)
Repo->>Adapter : findMany({filters})
Adapter-->>Repo : posts[]
Repo-->>Service : posts[]
Service-->>API : {posts, meta}
API-->>Client : 200 OK

Diagram sources

• post.controller.ts
• post.schema.ts
• post.service.ts
• post.repo.ts
• post.adapter.ts

Section sources

• post.controller.ts
• post.service.ts
• post.adapter.ts

Content Moderation Integration

• Dynamic banned-word matching powered by Aho-Corasick automata with strict and normal modes, plus wildcard support.
• Perspective API-based toxicity scoring with configurable thresholds and span-level detection.
• Fail-closed behavior on moderation service errors.

classDiagram
class ModeratorService {
+moderateText(input) IntegratedModerationResult
-ensureCompiled()
-validateContent(text) {allowed, reasons}
}
class CompiledModerationSet {
+strictMatcher : AhoCorasick
+normalMatcher : AhoCorasick
+normalVariantsMatcher : AhoCorasick
+wildcardPatterns
}
ModeratorService --> CompiledModerationSet : "builds/uses"

Diagram sources

• moderator.service.ts

Section sources

• moderator.service.ts

Real-Time Updates and Notifications

• Real-time notifications are currently commented out in the backend notification service module.
• The frontend exposes a socket hook and a Zustand store for managing posts locally, but live updates are not wired to the backend in the current codebase snapshot.

Section sources

• notification.service.ts
• useSocket.ts
• postStore.ts

Trending Algorithms and Content Discovery

• Trending posts are fetched by sorting by view count descending with a small fixed limit.
• The UI can integrate this endpoint to surface popular content.

Section sources

• post.ts

Dependency Analysis

The following diagram shows key dependencies among components involved in anonymous posting:

graph LR
Controller["PostController"] --> Service["PostService"]
Service --> Repo["PostRepo"]
Repo --> Adapter["PostAdapter"]
Adapter --> Table["posts table"]
Service --> Moderator["ModeratorService"]
Repo --> CacheKeys["Post Cache Keys"]
WebAPI["postApi (web)"] --> Controller
ModerationUtils["moderation utility (web)"] --> AdminModeration["moderationApi (admin)"]

Diagram sources

• post.controller.ts
• post.service.ts
• post.repo.ts
• post.adapter.ts
• post.table.ts
• moderator.service.ts
• post.cache-keys.ts
• post.ts
• moderation.ts
• moderation.ts (admin)

Section sources

• post.controller.ts
• post.service.ts
• post.repo.ts
• post.adapter.ts
• post.table.ts
• moderator.service.ts
• post.cache-keys.ts
• post.ts
• moderation.ts
• moderation.ts (admin)

Performance Considerations

• Caching: Post retrieval and counts are cached using versioned keys; mutations bump versions to invalidate caches.
• Database indexing: Visibility and sort indexes are defined on the posts table to optimize filtering and ordering.
• Moderation caching: Results are cached to reduce repeated moderation calls.

Recommendations:

• Monitor cache hit rates and tune TTLs for moderation and post lists.
• Add pagination-aware caching for trending endpoints.
• Consider precomputing trending aggregates if traffic grows.

Section sources

• post.cache-keys.ts
• post.adapter.ts
• moderator.service.ts

Troubleshooting Guide

Common issues and resolutions:

• Content policy violation during creation or update:
  • The moderation service returns violations with reasons and matched words; adjust content accordingly.
• Unauthorized access to private posts:
  • Ensure the user is authenticated and belongs to the same college as the post author.
• Not found errors:
  • Verify post IDs and that the post is not shadow/banned.
• Rate limiting or spam detection:
  • The validator flags excessive links or repeated characters; rewrite content respectfully.

Section sources

• post.service.ts
• post.service.ts
• moderator.service.ts
• moderator.service.ts

Conclusion

Flick’s anonymous posting system enforces strong content moderation, preserves user privacy, and provides robust filtering and discovery. The backend ensures ownership verification and privacy boundaries, while the frontend offers convenient APIs and client-side moderation utilities. Real-time updates and notifications are present in concept but not fully wired in the current snapshot.

Appendices

API Definitions and Examples

• Create a post:
  • Method: POST
  • Path: /posts
  • Body: { title, content, topic, isPrivate? }
  • Response: { post }
• Retrieve posts with filters:
  • Method: GET
  • Path: /posts
  • Query: { page?, limit?, sortBy?, sortOrder?, topic?, collegeId?, branch? }
  • Response: { posts[], meta }
• Retrieve trending posts:
  • Method: GET
  • Path: /posts
  • Query: { sortBy=views, sortOrder=desc, limit=5 }
  • Response: { posts[], meta }
• Update a post:
  • Method: PATCH
  • Path: /posts/{id}
  • Body: { title?, content?, topic?, isPrivate? }
  • Response: { post }
• Delete a post:
  • Method: DELETE
  • Path: /posts/{id}
  • Response: { message }
• Increment views:
  • Method: POST
  • Path: /posts/{id}/view
  • Response: { message }
• Filter by college:
  • Method: GET
  • Path: /posts/college/{collegeId}
  • Query: { page?, limit?, sortBy?, sortOrder? }
• Filter by branch:
  • Method: GET
  • Path: /posts/branch/{branch}
  • Query: { page?, limit?, sortBy?, sortOrder? }
• Filter by author:
  • Method: GET
  • Path: /posts/user/{userId}
  • Query: { page?, limit?, sortBy?, sortOrder? }

Section sources

• post.ts
• post.controller.ts
• post.schema.ts

Schema Validation Reference

• CreatePostSchema: Enforces title/content length limits, topic enumeration, optional isPrivate.
• UpdatePostSchema: Same as create with optional fields.
• GetPostsQuerySchema: Validates pagination, sorting, and topic normalization.
• PostIdSchema, CollegeIdSchema, BranchSchema: UUID and branch validations.

Section sources

• post.schema.ts

Moderation Configuration (Admin)

• List banned words and manage strict/normal modes and severities.
• Client-side moderation utility compiles and caches configuration for fast local checks.

Section sources

• moderation.ts (admin)
• moderation.ts