# timchatt/fieldwork architecture

> Architecture diagram of the GitHub repository timchatt/fieldwork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timchatt/fieldwork
- Repository: https://github.com/timchatt/fieldwork

## Overview

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: [`apps/api`](https://github.com/timchatt/fieldwork/tree/main/apps/api) (API), [`apps/web`](https://github.com/timchatt/fieldwork/tree/main/apps/web) (Web App), [`packages/db`](https://github.com/timchatt/fieldwork/tree/main/packages/db) (Database), [`packages/config`](https://github.com/timchatt/fieldwork/tree/main/packages/config) (Shared Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Applications"]
  node_web["Web App<br/>Next.js app"]
  node_web_app["App Routes<br/>route layer"]
  node_web_public["Public Flows<br/>route layer"]
  node_web_api_routes["Web API Routes<br/>route proxies"]
  node_web_trpc(("tRPC Client<br/>typed client"))
  node_api["API<br/>NestJS/Fastify app"]
  node_api_auth["Auth"]
  node_api_domain["Core Domains<br/>modules"]
  node_api_interviews["Interviews<br/>workflow module"]
  node_api_email["Email<br/>workflow module"]
  node_api_automation["Automation<br/>rules module"]
  node_api_analytics["Analytics<br/>reporting module"]
  node_api_queue["Queue Workers<br/>async processing"]
  node_api_trpc(("tRPC Routers<br/>typed RPC surface"))
end

subgraph group_packages["Shared Packages"]
  node_db[("Database<br/>PostgreSQL/Drizzle")]
  node_types["Shared Types<br/>contracts package"]
  node_ext["Browser Extension<br/>Chrome extension"]
  node_shared_config["Shared Config<br/>tooling package"]
end

node_web -->|"renders"| node_web_app
node_web -->|"serves"| node_web_public
node_web -->|"hosts"| node_web_api_routes
node_web -->|"calls"| node_web_trpc
node_web_api_routes -->|"auth proxy"| node_api_auth
node_web_api_routes -->|"tRPC proxy"| node_api_trpc
node_web_trpc -->|"RPC"| node_api_trpc
node_api -->|"includes"| node_api_auth
node_api -->|"organizes"| node_api_domain
node_api -->|"includes"| node_api_interviews
node_api -->|"includes"| node_api_email
node_api -->|"includes"| node_api_automation
node_api -->|"includes"| node_api_analytics
node_api -->|"dispatches"| node_api_queue
node_api -->|"exposes"| node_api_trpc
node_api -->|"reads/writes"| node_db
node_api_domain -->|"persists"| node_db
node_api_interviews -->|"offloads"| node_api_queue
node_api_email -->|"stores state"| node_db
node_api_automation -->|"executes"| node_api_queue
node_api_analytics -->|"queries"| node_db
node_ext -->|"syncs"| node_api
node_ext -->|"captures leads"| node_api_domain
node_types -->|"shared contracts"| node_web
node_types -->|"shared contracts"| node_api
node_shared_config -.->|"tooling"| node_web
node_shared_config -.->|"tooling"| node_api
node_shared_config -.->|"tooling"| node_ext

click node_web "https://github.com/timchatt/fieldwork/tree/main/apps/web"
click node_web_app "https://github.com/timchatt/fieldwork/tree/main/apps/web/app/(app)"
click node_web_public "https://github.com/timchatt/fieldwork/tree/main/apps/web/app"
click node_web_api_routes "https://github.com/timchatt/fieldwork/tree/main/apps/web/app/api"
click node_web_trpc "https://github.com/timchatt/fieldwork/tree/main/apps/web/lib/trpc"
click node_api "https://github.com/timchatt/fieldwork/tree/main/apps/api"
click node_api_auth "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/auth"
click node_api_domain "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules"
click node_api_interviews "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/interviews"
click node_api_email "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/email"
click node_api_automation "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/automation"
click node_api_analytics "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/analytics"
click node_api_queue "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/queue"
click node_api_trpc "https://github.com/timchatt/fieldwork/tree/main/apps/api/src/trpc/routers"
click node_db "https://github.com/timchatt/fieldwork/tree/main/packages/db"
click node_types "https://github.com/timchatt/fieldwork/tree/main/packages/types"
click node_ext "https://github.com/timchatt/fieldwork/tree/main/packages/extension"
click node_shared_config "https://github.com/timchatt/fieldwork/tree/main/packages/config"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_web_app,node_web_public,node_web_api_routes,node_web_trpc,node_api,node_api_auth,node_api_domain,node_api_interviews,node_api_email,node_api_automation,node_api_analytics,node_api_queue,node_api_trpc toneBlue
class node_db,node_types,node_ext,node_shared_config toneAmber
```

## Components

### Applications

Runtime surfaces for web, API, and extension.

- [Web App](https://github.com/timchatt/fieldwork/tree/main/apps/web): Next.js app · User-facing Next.js App Router frontend with authenticated and public flows. · `apps/web`
- [App Routes](https://github.com/timchatt/fieldwork/tree/main/apps/web/app/(app)): route layer · Authenticated product pages for dashboard, candidates, jobs, pipeline, reports, and settings. · `apps/web/app/(app)`
- [Public Flows](https://github.com/timchatt/fieldwork/tree/main/apps/web/app): route layer · Careers, application, scheduling, availability, referrals, and survey entry points. · `apps/web/app`
- [Web API Routes](https://github.com/timchatt/fieldwork/tree/main/apps/web/app/api): route proxies · Next.js API routes for auth, public submission, and tRPC transport. · `apps/web/app/api`
- [tRPC Client](https://github.com/timchatt/fieldwork/tree/main/apps/web/lib/trpc): typed client · Browser-side typed RPC access used by the web app. · `apps/web/lib/trpc`
- [API](https://github.com/timchatt/fieldwork/tree/main/apps/api): NestJS/Fastify app · Backend system of record for business logic, persistence, and integrations. · `apps/api`
- [Auth](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/auth): module · Better Auth integration and authentication controllers/services. · `apps/api/src/modules/auth`
- [Core Domains](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules): modules · Recruiting workflow modules for candidates, jobs, applications, pipeline, brands, users, and CRM/talent pools. · `apps/api/src/modules`
- [Interviews](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/interviews): workflow module · Scheduling, calendar integration, and interview processing across request and async paths. · `apps/api/src/modules/interviews`
- [Email](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/email): workflow module · Email OAuth, sync, and template services. · `apps/api/src/modules/email`
- [Automation](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/automation): rules module · Rule evaluation and automation execution. · `apps/api/src/modules/automation`
- [Analytics](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/analytics): reporting module · Read-optimized recruiting reports and funnel queries. · `apps/api/src/modules/analytics`
- [Queue Workers](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/modules/queue): async processing · Redis-backed workers for analytics, automation, sequences, surveys, and interview scheduling. · `apps/api/src/modules/queue`
- [tRPC Routers](https://github.com/timchatt/fieldwork/tree/main/apps/api/src/trpc/routers): typed RPC surface · 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](https://github.com/timchatt/fieldwork/tree/main/packages/db): PostgreSQL/Drizzle · Schema, migrations, seed data, and DB client shared across backend features. · `packages/db`
- [Shared Types](https://github.com/timchatt/fieldwork/tree/main/packages/types): contracts package · Shared domain types and Zod-style contracts for app and API payloads. · `packages/types`
- [Browser Extension](https://github.com/timchatt/fieldwork/tree/main/packages/extension): Chrome extension · Background, content, popup, and sidebar surfaces for sourcing and capture workflows. · `packages/extension`
- [Shared Config](https://github.com/timchatt/fieldwork/tree/main/packages/config): tooling package · Common ESLint, TypeScript, and Tailwind configuration. · `packages/config`

## Connections

- 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.
