Repository Map: Where to Change What

This guide maps common development tasks to the specific files you need to modify.

Quick Reference Table

Change Type	Primary Files	Supporting Files
Add API endpoint	server/routes.ts	server/storage.ts
Add database table	shared/schema.ts	Run npm run db:push
Modify assessment logic	server/lib/assessmentPipeline.ts	server/lib/llmProvider.ts
Add UI component	client/src/components/	client/src/lib/api.ts
Add new page	client/src/pages/	client/src/App.tsx
Change vector search	server/lib/vectorStore.ts	shared/schema.ts

Detailed Change Guide

1. Add a new API endpoint

Files to edit:

• server/routes.ts - Add route handler

Pattern (verified from existing routes):

app.get("/api/your-endpoint", async (req: Request, res: Response) => {
  const tenantId = requireTenant(req, res);
  if (!tenantId) return;
  
  // Your logic here
  res.json({ data });
});

Tenant isolation: Always use requireTenant() helper (lines 161-172) to get tenant ID securely.

2. Add a new database table

Files to edit:

• shared/schema.ts - Define table, insert schema, and types

Pattern (verified from shared/schema.ts):

export const yourTable = pgTable("your_table", {
  id: varchar("id").primaryKey().default(sql`gen_random_uuid()`),
  tenantId: varchar("tenant_id").notNull().references(() => tenants.id),
  // ... columns
  createdAt: timestamp("created_at").defaultNow().notNull()
}, (table) => ({
  tenantIdx: index("your_table_tenant_idx").on(table.tenantId)
}));

export const insertYourTableSchema = createInsertSchema(yourTable).omit({
  id: true,
  createdAt: true
});

export type InsertYourTable = z.infer<typeof insertYourTableSchema>;
export type YourTable = typeof yourTable.$inferSelect;

Required: Always include tenantId with foreign key to tenants.id and add tenant index.

After editing: Run npm run db:push to sync schema.

3. Add a new status enum

Files to edit:

• shared/schema.ts - Define the enum constant and type

Pattern (verified from shared/schema.ts:160-169):

export const YourStatus = {
  STATE_A: "STATE_A",
  STATE_B: "STATE_B",
  STATE_C: "STATE_C"
} as const;

export type YourStatusType = typeof YourStatus[keyof typeof YourStatus];

4. Modify evidence processing pipeline

Files to edit:

• server/lib/pipeline.ts - Main orchestration
• server/lib/contentExtractor.ts - Text extraction from files
• server/lib/chunker.ts - Text segmentation
• server/lib/evidenceStorage.ts - File storage with SHA256

Status transitions (verified from shared/schema.ts:160-167):

UPLOADED → EXTRACTED → PARSED → INDEXED → READY
                                           └─► FAILED

5. Modify assessment logic

Files to edit:

• server/lib/assessmentPipeline.ts - Main assessment flow
• server/lib/llmProvider.ts - LLM prompt and response handling
• server/lib/vectorStore.ts - Similarity search

Key constants (server/lib/assessmentPipeline.ts:14-17):

const SIMILARITY_THRESHOLD = 0.20;
const FALLBACK_THRESHOLD = 0.10;
const TOP_K = 10;
const REQUIREMENT_TIMEOUT_MS = 90000; // 90 seconds per requirement

6. Add a new frontend page

Files to edit:

• client/src/pages/YourPage.tsx - Create the page component
• client/src/App.tsx - Register route

Pattern (verified from client/src/App.tsx):

import YourPage from "./pages/YourPage";

// In App component:
<Route path="/your-path" component={YourPage} />

Routing library: Uses wouter, not react-router.

7. Modify pack resolution logic

Files to edit:

• server/lib/packResolver.ts - Binding resolution
• server/lib/packSafetyService.ts - Immutability enforcement

Key function (server/lib/packResolver.ts:25):

• resolvePackBinding(tenantId, packId, environment) - Returns all effective bindings

Binding types resolved (interface at lines 12-23):

• criteriaVersionId
• corpusActivationId
• retrievalVersionId, promptVersionId, chunkingVersionId, agentVersionId

8. Add tracing to a new operation

Files to edit:

• server/lib/tracing.ts - Add span functions if needed
• Your service file - Use existing span functions

Pattern (verified from server/lib/tracing.ts:178-195):

import { startStepSpan, endSpan } from "./tracing";

const stepTrace = startStepSpan({
  runId,
  tenantId,
  packId,
  stepName: "your_step_name",
  inputRefs: { /* allowed attributes only */ }
}, parentSpan);

// ... your operation

endSpan(stepTrace.span, "success", {
  latencyMs: Date.now() - startTime
});

Allowed attributes: See allowlist at server/lib/tracing.ts:7-47.

9. Add an audit event

Files to edit:

• shared/schema.ts - Add to AuditAction enum if new action type
• server/lib/audit.ts - Use appendAuditEvent()

Pattern (verified from server/lib/audit.ts):

await appendAuditEvent({
  tenantId,
  packId,
  actorType: "SYSTEM",
  eventType: "YOUR_EVENT",
  objectType: "YOUR_OBJECT_TYPE",
  objectId: objectId,
  runId: runId,
  metadata: { key: "value" }
});

10. Modify file upload limits

Files to edit:

• server/routes.ts - Multer configuration (line 88)

Current config:

const upload = multer({ 
  storage: multer.memoryStorage(), 
  limits: { fileSize: 100 * 1024 * 1024 } // 100MB
});

ZIP limits (shared/schema.ts:176-179):

export const ZIP_LIMITS = {
  MAX_DEPTH: 5,
  MAX_FILES: 1000,
  MAX_TOTAL_SIZE_BYTES: 500 * 1024 * 1024 // 500MB
} as const;

11. Add allowed file type

Files to edit:

• shared/schema.ts - Update ALLOWED_FILE_TYPES (line 172)
• server/lib/contentExtractor.ts - Add extraction logic for new type

Current allowed types:

export const ALLOWED_FILE_TYPES = ["pdf", "docx", "xlsx", "csv", "png", "jpg", "jpeg", "zip", "txt"] as const;

12. Modify tenant security

Files to edit:

• server/routes.ts - Security helpers (lines 107-172)

Key functions:

• resolveTenantSecure() - Core resolution logic with override checks
• requireTenant() - Express helper for routes

Security rules (documented at lines 90-98):

1. Session tenant is primary source
2. Query param override requires SUPER_ADMIN_MODE=true AND SUPER_ADMIN role
3. No silent fallbacks - missing tenant = 400/403

13. Add evaluation metric

Files to edit:

• server/lib/evaluationService.ts - Evaluation logic
• shared/schema.ts - Add metric field to run_evaluations table if needed

14. Modify export formats

Files to edit:

• server/lib/exportService.ts - Export generation

Key functions:

• generateCSVExport() - CSV matrix format
• generateJSONExport() - JSON report format
• generateBinderManifest() - Evidence binder

Export types (shared/schema.ts:515-519):

export const ExportType = {
  CSV_MATRIX: "csv_matrix",
  JSON_REPORT: "json_report",
  EVIDENCE_BINDER: "evidence_binder"
} as const;

File Ownership by Domain

Evidence Domain

• server/lib/evidenceStorage.ts - File storage
• server/lib/contentExtractor.ts - Text extraction
• server/lib/chunker.ts - Text segmentation
• server/lib/pipeline.ts - Orchestration

Assessment Domain

• server/lib/assessmentPipeline.ts - Main flow
• server/lib/llmProvider.ts - LLM integration
• server/lib/vectorStore.ts - Similarity search
• server/lib/taskGenerator.ts - Remediation tasks

Configuration Domain

• server/lib/packResolver.ts - Binding resolution
• server/lib/packSafetyService.ts - Immutability
• server/lib/engineResolver.ts - Engine config normalization

Observability Domain

• server/lib/tracing.ts - OpenTelemetry spans
• server/lib/adminService.ts - Audit logs, run management
• server/lib/metricsService.ts - Metrics aggregation

Export Domain

• server/lib/exportService.ts - All export formats

Related Pages

• Architecture Overview - System design
• Data Model - Schema reference
• Determinism and Replay - Snapshot pinning