How timchatt/fieldwork works
1. Repository shape
- This is a monorepo with three main runtime surfaces: a Next.js web app, a NestJS/Fastify API, and a browser extension.
- Shared foundation lives in packages/: database schema/migrations, shared domain types, and shared lint/TS config.
2. Primary runtime boundaries
- apps/web runs the user-facing UI on localhost:3000.
- apps/api runs the backend on localhost:3001.
- The backend is the system of record and owns business logic, persistence, queue workers, and external integrations.
3. Web application
- The web app uses the Next.js App Router and is split into authenticated app pages and public flows.
- Internal product areas include dashboard, candidates, jobs, pipeline, reports, talent pools, and settings.
- Public-facing pages include careers pages, application flow, scheduling, availability, referrals, and surveys.
- Web-side API routes proxy auth and public submission flows, and a tRPC client is used for typed API access.
4. Backend application
- The API is organized as NestJS modules with a mix of controllers and services, plus a separate tRPC router layer.
- REST-style controllers appear for auth, users, jobs, candidates, pipeline, interviews, brands, applications, email OAuth, and public-facing operations.
- tRPC routers mirror many product domains and are the main typed RPC surface for the web app.
5. Domain decomposition
- Core business modules are centered around recruiting workflows: candidates, jobs, applications, pipeline, interviews, sequences, automation, surveys, referrals, sourcing, email, analytics, brands, users, storage, and CRM/talent pools.
- The code structure suggests the API is a domain-oriented monolith rather than a set of microservices.
6. Multi-brand model
- The app is explicitly designed for one organization with multiple brands, not a generic multi-tenant SaaS.
- Brand-scoped resources include jobs, pipelines, applications, hiring teams, and brand-specific user roles.
- Candidates are global/shared across brands, which is an important architectural boundary for data modeling and authorization.
7. Persistence layer
- packages/db contains the Drizzle schema, migrations, seed data, and DB client.
- Schema files are organized by domain, matching the application modules, which makes the database the shared contract between backend features.
- PostgreSQL is the primary database, and the README indicates migrations and seed data are part of the standard workflow.
8. Shared types and contracts
- packages/types holds shared domain types/Zod-style contracts for analytics, applications, automation, brand, candidate, CRM, email, interview, job, referrals, sequences, surveys, and users.
- This package reduces drift between backend logic, frontend forms, and extension/API payloads.
- packages/config provides shared tooling configuration, not product runtime behavior.
9. Async processing and queues
- Redis backs background processing via queue infrastructure in apps/api/src/modules/queue and apps/api/src/common/queue.
- Worker/processor files show separate asynchronous execution for analytics, automation, sequences, surveys, and interview-related scheduling/calendar tasks.
- This means time-consuming operations are intentionally split from request/response flows.
10. External integrations
- Authentication uses Better Auth.
- File storage uses MinIO/S3-compatible storage for resumes and assets.
- Email integration uses Resend when configured.
- Interview scheduling integrates with Google Calendar and Microsoft Calendar.
- The architecture therefore depends on local infrastructure plus several optional SaaS integrations.
11. Automation, email, and interviews
- Automation is its own subsystem with a rule evaluator and worker execution path.
- Email has separate services for OAuth, sync, and templates, implying inbound/outbound email handling is a first-class workflow.
- Interviews have dedicated scheduling, calendar, and worker components, indicating a workflow that spans UI, API, background jobs, and calendar providers.
12. Analytics/reporting
- Analytics is isolated into its own module with query files for funnel, time-to-hire, interviewer load, offer acceptance, recruiter productivity, source effectiveness, and DEI.
- This suggests a read-optimized reporting layer built from domain data rather than a separate analytics database.
13. Browser extension
- packages/extension is a Chrome-extension-style client with background, content, popup, and sidebar surfaces.
- It includes LinkedIn scraping and local auth/API helpers, so it acts as an external capture/surface for sourcing workflows rather than part of the core web app.
14. End-to-end architecture flow
- Users interact through the web app or extension.
- Requests go to the API via REST/tRPC.
- The API validates/authenticates, applies brand context, reads/writes PostgreSQL, uploads files to S3/MinIO, and enqueues background work in Redis.
- Workers perform async automation, analytics, sequence, survey, and scheduling tasks, while external providers handle auth, email, and calendars.
Main entry points: api API · web Web App · db Database · config Shared Config
Components 18
Applications
Runtime surfaces for web, API, and extension.
- Web App · User-facing Next.js App Router frontend with authenticated and public flows.
apps/web - App Routes · Authenticated product pages for dashboard, candidates, jobs, pipeline, reports, and settings.
apps/web/app/(app) - Public Flows · Careers, application, scheduling, availability, referrals, and survey entry points.
apps/web/app - Web API Routes · Next.js API routes for auth, public submission, and tRPC transport.
apps/web/app/api - tRPC Client · Browser-side typed RPC access used by the web app.
apps/web/lib/trpc - API · Backend system of record for business logic, persistence, and integrations.
apps/api - Auth · Better Auth integration and authentication controllers/services.
apps/api/src/modules/auth - Core Domains · Recruiting workflow modules for candidates, jobs, applications, pipeline, brands, users, and CRM/talent pools.
apps/api/src/modules - Interviews · Scheduling, calendar integration, and interview processing across request and async paths.
apps/api/src/modules/interviews - Email · Email OAuth, sync, and template services.
apps/api/src/modules/email - Automation · Rule evaluation and automation execution.
apps/api/src/modules/automation - Analytics · Read-optimized recruiting reports and funnel queries.
apps/api/src/modules/analytics - Queue Workers · Redis-backed workers for analytics, automation, sequences, surveys, and interview scheduling.
apps/api/src/modules/queue - tRPC Routers · Domain routers exposed to the web app for typed backend access.
apps/api/src/trpc/routers
Shared Packages
Database, types, config, and extension support code.
- Database · Schema, migrations, seed data, and DB client shared across backend features.
packages/db - Shared Types · Shared domain types and Zod-style contracts for app and API payloads.
packages/types - Browser Extension · Background, content, popup, and sidebar surfaces for sourcing and capture workflows.
packages/extension - Shared Config · Common ESLint, TypeScript, and Tailwind configuration.
packages/config
Connections 28
- Web App → App Routes: renders · Authenticated product UI is served from app routes.
- Web App → Public Flows: serves · Public-facing candidate and applicant flows live here.
- Web App → Web API Routes: hosts · Web app exposes auth and submission proxy routes.
- Web App → tRPC Client: calls · Frontend uses typed RPC client for backend access.
- Web API Routes → Auth: auth proxy · Next.js routes proxy login, logout, signup, and brand auth.
- Web API Routes → tRPC Routers: tRPC proxy · API routes forward typed RPC traffic.
- tRPC Client → tRPC Routers: RPC · Browser client talks to backend routers.
- API → Auth: includes · Backend composes authentication as a first-class module.
- API → Core Domains: organizes · Main business logic lives in domain modules.
- API → Interviews: includes · Interview workflow spans controllers, services, and workers.
- API → Email: includes · Email handling is a dedicated subsystem.
- API → Automation: includes · Automation rules and execution are isolated.
- API → Analytics: includes · Reporting and analytics are separate from transactional flows.
- API → Queue Workers: dispatches · Backend enqueues long-running work to Redis workers.
- API → tRPC Routers: exposes · Typed RPC layer mirrors core domains.
- API → Database: reads/writes · Backend persists system of record data in PostgreSQL.
- Core Domains → Database: persists · Domain modules map to schema and migrations.
- Interviews → Queue Workers: offloads · Scheduling and calendar tasks run asynchronously.
- Email → Database: stores state · OAuth, sync, and templates rely on persisted records.
- Automation → Queue Workers: executes · Rule evaluation drives queued automation work.
- Analytics → Database: queries · Reports are derived from operational data.
- Browser Extension → API: syncs · Extension uses backend API helpers for capture and auth.
- Browser Extension → Core Domains: captures leads · Sourcing workflow feeds candidate data into backend domains.
- Shared Types → Web App: shared contracts · Frontend form and API payload shapes are aligned.
- Shared Types → API: shared contracts · Backend and frontend share domain contracts.
- Shared Config → Web App: tooling · Shared config supports the web app build and linting.
- Shared Config → API: tooling · Shared config supports backend TypeScript and lint setup.
- Shared Config → Browser Extension: tooling · Shared config supports the extension build and linting.