Skip to main content

Signal Status Refactor Implementation Guide

Overview​

This guide provides step-by-step instructions for completing the unified signal status system refactor across the entire CivStart application.

Completed Work​

✅ Database Schema​

  • Updated Signal model with unified status system
  • Added isPublic flag to replace SignalPoolEntry
  • Updated SignalAssignment with assignmentType
  • Updated ContactRequest with requestSource and connectionId
  • Updated SignalPoolView and SignalPoolRequest to reference Signal directly
  • Removed SignalPoolEntry model
  • Applied migration to development database
  • Generated Prisma client

✅ Backend Types & Services​

  • Created signal status types and enums (apps/backend/src/govintel/types/signal-status.types.ts)
  • Created signal status service (apps/backend/src/govintel/services/signals/signal-status.service.ts)
  • Created signal status DTOs (apps/backend/src/govintel/dto/signal-status.dto.ts)

✅ Frontend Components​

  • Created SignalStatusBadge component for admin (apps/admin/components/SignalStatusBadge.tsx)
  • Created SignalStatusBadge component for frontend (apps/frontend/components/SignalStatusBadge.tsx)

Remaining Work​

1. Backend Controllers​

1.1 Update GovIntel Controller (apps/backend/src/govintel/controllers/govintel.controller.ts)​

Add new endpoints:

import { SignalStatusService } from '../services/signals/signal-status.service';
import {
AssignSignalToStartupsDto,
PublishToPoolDto,
ChangeSignalStatusDto,
ArchiveSignalDto,
UnarchiveSignalDto,
QuerySignalsDto,
} from '../dto/signal-status.dto';

// Inject SignalStatusService in constructor

/**
* POST /signals/:id/assign
* Assign signal to startups (direct assignment)
*/
@Post(':id/assign')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async assignSignalToStartups(
@Param('id') signalId: string,
@Body() dto: AssignSignalToStartupsDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.assignToStartups({
signalId,
...dto,
assignedBy: user.id,
});
}

/**
* POST /signals/:id/publish
* Publish signal to public pool
*/
@Post(':id/publish')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async publishToPool(
@Param('id') signalId: string,
@Body() dto: PublishToPoolDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.publishToPool({
signalId,
...dto,
publishedBy: user.id,
});
}

/**
* POST /signals/:id/unpublish
* Remove signal from public pool
*/
@Post(':id/unpublish')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async unpublishFromPool(
@Param('id') signalId: string,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.unpublishFromPool(signalId, user.id);
}

/**
* POST /signals/:id/archive
* Archive a signal
*/
@Post(':id/archive')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async archiveSignal(
@Param('id') signalId: string,
@Body() dto: ArchiveSignalDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.archiveSignal(signalId, user.id, dto.notes);
}

/**
* POST /signals/:id/unarchive
* Unarchive a signal
*/
@Post(':id/unarchive')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async unarchiveSignal(
@Param('id') signalId: string,
@Body() dto: UnarchiveSignalDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.unarchiveSignal(signalId, user.id, dto.notes);
}

/**
* GET /signals/:id/status-history
* Get status change history
*/
@Get(':id/status-history')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async getStatusHistory(@Param('id') signalId: string) {
return this.signalStatusService.getStatusHistory(signalId);
}

1.2 Update Signal Pool Controller (apps/backend/src/govintel/controllers/signal-pool.controller.ts)​

Update existing methods to use the new system:

/**
* GET /signal-pool
* Get public pool signals (use isPublic flag instead of SignalPoolEntry)
*/
@Get()
@UseGuards(ClerkAuthGuard)
async getPublicPoolSignals(
@Query() query: QueryPoolSignalsDto,
@GetUser() user: ClerkUser,
) {
const { page = 1, limit = 20, visibilityLevel, solutionCategory, search } = query;

const where: any = {
isPublic: true,
isActive: true,
isArchived: false,
};

if (visibilityLevel) {
where.visibilityLevel = visibilityLevel;
}

if (solutionCategory) {
where.solutionCategory = solutionCategory;
}

if (search) {
where.OR = [
{ title: { contains: search, mode: 'insensitive' } },
{ description: { contains: search, mode: 'insensitive' } },
];
}

const [signals, total] = await Promise.all([
this.prisma.signal.findMany({
where,
take: limit,
skip: (page - 1) * limit,
orderBy: { publishedAt: 'desc' },
include: {
government: true,
governmentContact: true,
},
}),
this.prisma.signal.count({ where }),
]);

return {
signals,
pagination: {
page,
limit,
total,
totalPages: Math.ceil(total / limit),
},
};
}

/**
* POST /signal-pool/:signalId/accept
* Startup accepts signal from pool and creates assignment
*/
@Post(':signalId/accept')
@UseGuards(ClerkAuthGuard)
async acceptPoolSignal(
@Param('signalId') signalId: string,
@Body() dto: AcceptPoolSignalDto,
@GetUser() user: ClerkUser,
) {
// Create assignment with type="pool"
const assignment = await this.signalStatusService.assignToStartups({
signalId,
startupIds: [user.startupId], // Get from user context
assignedBy: user.id,
assignmentType: AssignmentType.POOL,
});

// Accept the signal
await this.signalStatusService.acceptSignal(signalId, user.startupId, user.id);

return { success: true, assignment };
}

/**
* POST /signal-pool/:signalId/view
* Track that a startup viewed a pool signal
*/
@Post(':signalId/view')
@UseGuards(ClerkAuthGuard)
async trackPoolView(
@Param('signalId') signalId: string,
@GetUser() user: ClerkUser,
) {
// Create or update view record
await this.prisma.signalPoolView.upsert({
where: {
signalId_startupId: {
signalId,
startupId: user.startupId,
},
},
create: {
signalId,
startupId: user.startupId,
viewedAt: new Date(),
},
update: {
viewedAt: new Date(),
},
});

// Increment view count
await this.prisma.signal.update({
where: { id: signalId },
data: { viewCount: { increment: 1 } },
});

return { success: true };
}

1.3 Create Startup Controller Endpoints (apps/backend/src/govintel/controllers/startup.controller.ts)​

/**
* POST /startup/signals/:signalId/accept
* Accept assigned signal
*/
@Post('signals/:signalId/accept')
@UseGuards(ClerkAuthGuard)
async acceptSignal(
@Param('signalId') signalId: string,
@Body() dto: AcceptSignalDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.acceptSignal(signalId, user.startupId, user.id);
}

/**
* POST /startup/signals/:signalId/decline
* Decline assigned signal
*/
@Post('signals/:signalId/decline')
@UseGuards(ClerkAuthGuard)
async declineSignal(
@Param('signalId') signalId: string,
@Body() dto: DeclineSignalDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.declineSignal(signalId, user.startupId, user.id, dto.reason);
}

/**
* POST /startup/signals/:signalId/request-contact
* Request contact information (unified for direct and pool)
*/
@Post('signals/:signalId/request-contact')
@UseGuards(ClerkAuthGuard)
async requestContact(
@Param('signalId') signalId: string,
@Body() dto: CreateContactRequestDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.createContactRequest({
signalId,
startupId: user.startupId,
...dto,
requestedBy: user.id,
});
}

1.4 Update Contact Request Controller​

/**
* POST /contact-requests/:id/approve
* Approve contact request
*/
@Post(':id/approve')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async approveContactRequest(
@Param('id') requestId: string,
@Body() dto: ReviewContactRequestDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.approveContactRequest(
requestId,
user.id,
dto.reviewNotes
);
}

/**
* POST /contact-requests/:id/reject
* Reject contact request
*/
@Post(':id/reject')
@UseGuards(ClerkAuthGuard, RolesGuard)
@Roles('admin')
async rejectContactRequest(
@Param('id') requestId: string,
@Body() dto: ReviewContactRequestDto,
@GetUser() user: ClerkUser,
) {
return this.signalStatusService.rejectContactRequest(
requestId,
user.id,
dto.reviewNotes
);
}

2. Frontend API Clients​

2.1 Update Admin API Client (apps/admin/lib/api-client.ts)​

Add new methods:

export class AdminApiClient {
// ... existing methods ...

// Signal status management
async assignSignalToStartups(
signalId: string,
dto: AssignSignalToStartupsDto,
) {
return this.post(`/govintel/signals/${signalId}/assign`, dto);
}

async publishToPool(signalId: string, dto: PublishToPoolDto) {
return this.post(`/govintel/signals/${signalId}/publish`, dto);
}

async unpublishFromPool(signalId: string) {
return this.post(`/govintel/signals/${signalId}/unpublish`, {});
}

async archiveSignal(signalId: string, notes?: string) {
return this.post(`/govintel/signals/${signalId}/archive`, { notes });
}

async unarchiveSignal(signalId: string, notes?: string) {
return this.post(`/govintel/signals/${signalId}/unarchive`, { notes });
}

async getStatusHistory(signalId: string) {
return this.get(`/govintel/signals/${signalId}/status-history`);
}

// Contact request management
async approveContactRequest(requestId: string, reviewNotes?: string) {
return this.post(`/contact-requests/${requestId}/approve`, {
decision: "approved",
reviewNotes,
});
}

async rejectContactRequest(requestId: string, reviewNotes?: string) {
return this.post(`/contact-requests/${requestId}/reject`, {
decision: "rejected",
reviewNotes,
});
}
}

2.2 Update Startup API Client (apps/frontend/lib/api-client.ts)​

export class StartupApiClient {
// ... existing methods ...

// Signal actions
async acceptSignal(signalId: string, notes?: string) {
return this.post(`/startup/signals/${signalId}/accept`, { notes });
}

async declineSignal(signalId: string, reason?: string) {
return this.post(`/startup/signals/${signalId}/decline`, { reason });
}

async requestContact(signalId: string, requestSource: "direct" | "pool") {
return this.post(`/startup/signals/${signalId}/request-contact`, {
requestSource,
});
}

// Pool actions
async getPoolSignals(params?: {
page?: number;
limit?: number;
solutionCategory?: string;
search?: string;
}) {
return this.get("/signal-pool", { params });
}

async acceptPoolSignal(signalId: string, justification?: string) {
return this.post(`/signal-pool/${signalId}/accept`, { justification });
}

async trackPoolView(signalId: string) {
return this.post(`/signal-pool/${signalId}/view`, {});
}
}

3. Admin Pages​

3.1 Update Signals List Page (apps/admin/app/signals/page.tsx)​

import { SignalStatusBadge, STATUS_FILTER_OPTIONS } from '@/components/SignalStatusBadge';

// Add status filter
const [statusFilter, setStatusFilter] = useState('');

// Add filter UI
<Select value={statusFilter} onValueChange={setStatusFilter}>
<SelectTrigger>
<SelectValue placeholder="Filter by status" />
</SelectTrigger>
<SelectContent>
{STATUS_FILTER_OPTIONS.map(option => (
<SelectItem key={option.value} value={option.value}>
{option.label}
</SelectItem>
))}
</SelectContent>
</Select>

// Display status in table
<TableCell>
<SignalStatusBadge
status={signal.status}
isPublic={signal.isPublic}
showPublicIndicator={true}
/>
</TableCell>

3.2 Update Signal Detail Page (apps/admin/app/signals/[id]/page.tsx)​

Add action buttons based on status:

import { SignalStatusBadge } from '@/components/SignalStatusBadge';

// Status display
<SignalStatusBadge
status={signal.status}
isPublic={signal.isPublic}
showPublicIndicator={true}
/>

// Action buttons
{signal.status === 'signal_unassigned' && (
<>
<Button onClick={handleAssignToStartups}>Assign to Startups</Button>
<Button onClick={handlePublishToPool}>Publish to Pool</Button>
</>
)}

{signal.isPublic && signal.status === 'signal_assigned' && (
<Button onClick={handleUnpublishFromPool}>Remove from Pool</Button>
)}

{!signal.isArchived && (
<Button variant="destructive" onClick={handleArchive}>Archive</Button>
)}

3.3 Update Contact Requests Page (apps/admin/app/contact-requests/page.tsx)​

// Add approval/rejection actions
async function handleApprove(requestId: string) {
const notes = window.prompt('Review notes (optional):');
await apiClient.approveContactRequest(requestId, notes);
toast.success('Contact request approved');
refetch();
}

async function handleReject(requestId: string) {
const notes = window.prompt('Rejection reason:');
if (!notes) return;
await apiClient.rejectContactRequest(requestId, notes);
toast.success('Contact request rejected');
refetch();
}

// Display in table
<TableCell>
{request.status === 'pending' && (
<>
<Button size="sm" onClick={() => handleApprove(request.id)}>Approve</Button>
<Button size="sm" variant="destructive" onClick={() => handleReject(request.id)}>Reject</Button>
</>
)}
{request.status === 'approved' && <Badge variant="default">Approved</Badge>}
{request.status === 'rejected' && <Badge variant="destructive">Rejected</Badge>}
</TableCell>

4. Startup (Frontend) Pages​

4.1 Update Inbox Page (apps/frontend/app/inbox/page.tsx)​

import { SignalStatusBadge, canTakeAction, getAvailableActions } from '@/components/SignalStatusBadge';

// Display status
<SignalStatusBadge
status={signal.status}
showDescription={true}
/>

// Action buttons
{canTakeAction(signal.status) && (
<div className="flex gap-2">
{getAvailableActions(signal.status).includes('accept') && (
<Button onClick={() => handleAccept(signal.id)}>Accept</Button>
)}
{getAvailableActions(signal.status).includes('decline') && (
<Button variant="outline" onClick={() => handleDecline(signal.id)}>Decline</Button>
)}
{getAvailableActions(signal.status).includes('request_contact') && (
<Button onClick={() => handleRequestContact(signal.id)}>Request Contact Info</Button>
)}
</div>
)}

4.2 Update Pool Page (apps/frontend/app/pool/page.tsx)​

// Fetch pool signals
const { data, isLoading } = useQuery({
queryKey: ["pool-signals", filters],
queryFn: () => apiClient.getPoolSignals(filters),
});

// Accept pool signal
async function handleAcceptPoolSignal(signalId: string) {
const justification = window.prompt("Why is this a good fit? (optional):");
await apiClient.acceptPoolSignal(signalId, justification);
toast.success("Signal accepted! Check your inbox.");
router.push("/inbox");
}

// Track views
useEffect(() => {
if (viewedSignalId) {
apiClient.trackPoolView(viewedSignalId);
}
}, [viewedSignalId]);

5. Testing​

5.1 Test Scenarios​

  1. Admin assigns signal directly to startup

    • Signal: unassigned → assigned
    • SignalAssignment created with type="direct"
    • Startup sees in inbox with "New" status
  2. Admin publishes signal to pool

    • Signal: unassigned → assigned, isPublic=true
    • Signal appears in public pool
    • All startups can view it
  3. Startup accepts from pool

    • SignalAssignment created with type="pool"
    • Signal: assigned → accepted
    • Startup can request contact
  4. Startup accepts direct assignment

    • Signal: assigned → accepted
    • Startup can request contact
  5. Startup requests contact (both flows)

    • Signal: accepted → contact_request_pending
    • ContactRequest created with appropriate requestSource
    • Admin can approve/reject
  6. Admin approves contact request

    • Signal: contact_request_pending → contact_request_approved
    • Connection created
    • ContactRequest.connectionId linked
  7. Admin rejects contact request

    • Signal: contact_request_pending → contact_request_rejected
    • Startup can see rejection
  8. Admin archives signal

    • Signal: any → archived
    • No longer appears in active views

6. Migration Checklist​

  • Update backend controllers with new endpoints
  • Update frontend API clients
  • Update admin signals list page
  • Update admin signal detail page
  • Update admin contact requests page
  • Update startup inbox page
  • Update startup pool page
  • Add tests for new status transitions
  • Update API documentation
  • Deploy to staging environment
  • Test all workflows end-to-end
  • Deploy to production
  • Remove legacy approval status fields (future PR)

Key Concepts​

Status Machine​

The status transitions are strictly enforced by SIGNAL_STATUS_TRANSITIONS in the service. Invalid transitions throw errors.

Unified Contact Request Flow​

Both direct assignments and pool signals use the same contact request process after acceptance. The only difference is the requestSource field.

Public Pool​

The isPublic flag replaces the entire SignalPoolEntry table. Much simpler to manage and query.

Assignment Types​

SignalAssignment.assignmentType tracks whether a startup got the signal via:

  • direct: Admin assigned directly
  • pool: Startup accepted from public pool

This helps with analytics and reporting.


Support​

For questions or issues during implementation:

  1. Review the existing service code in signal-status.service.ts
  2. Check the status transition map in signal-status.types.ts
  3. Refer to the Prisma schema for data structure
  4. Test status transitions in development before deploying

Notes​

  • Legacy approvalStatus fields are kept temporarily for backward compatibility
  • They can be removed in a future PR after confirming all code uses the new system
  • The migration SQL is designed to be safe and reversible if needed