How soult-io/wagon-payroll works
Wagon Payroll is a small-business payroll web application: admins manage workers and monthly payroll, while employees access payslips, invoices, profiles, and change requests. The Vue SPA calls a Fastify API, which owns payroll and related business workflows and persists data in Postgres. Payroll calculations are centralized in the deterministic engine; filing and tax-deposit features track obligations but leave actual filing and payment to administrators. The map preserves documented capabilities, but some route-to-service wiring is unsampled and is shown only where supported by the README or app registration.
Main entry points: app.ts Fastify API · schema.ts Postgres data · runs.ts Payroll lifecycle · App.vue Payroll SPA
Components 21
Web application
- Payroll SPA
apps/web/src/App.vue - Web auth client
apps/web/src/lib/auth-client.ts
API and workflows
- Fastify API
apps/server/src/app.ts - Payroll routes
apps/server/src/routes/admin-payroll.ts - Employee services
apps/server/src/routes/my.ts - Change requests
apps/server/src/change-requests/service.ts - Contractor workflow
apps/server/src/contractors/service.ts
Payroll and records
- Payroll lifecycle
apps/server/src/payroll/runs.ts - Payroll engine
packages/engine/src/payroll.ts - Payroll documents
packages/documents/src/w2.ts - Postgres data
packages/db/src/schema.ts
Tax compliance
- Tax deposits
apps/server/src/deposits/service.ts - Tax filings
apps/server/src/filings/service.ts - Obligations calendar
apps/server/src/calendar/service.ts
Platform services
- Authentication
apps/server/src/auth/auth.ts - Notification outbox
apps/server/src/notify/outbox.ts - Legacy importer
apps/server/src/migrate/cli.ts
Other components
- Admins
- Employees
- Legacy accounting DB
- SMTP service
Connections 27
- Admins → Payroll SPA: use admin UI
- Employees → Payroll SPA: use self-service
- Payroll SPA → Fastify API: call API
- Payroll SPA → Web auth client: authenticate via
- Web auth client → Fastify API: auth requests
- Fastify API → Authentication: create auth
- Fastify API → Payroll routes: register routes
- Payroll routes → Payroll lifecycle: manage payroll
- Payroll lifecycle → Payroll engine: calculate payroll
- Payroll lifecycle → Postgres data: persist runs
- Payroll lifecycle → Payroll documents: generate documents
- Fastify API → Employee services: register routes
- Fastify API → Change requests: register routes
- Change requests → Postgres data: update employee data
- Fastify API → Contractor workflow: register contractor routes
- Contractor workflow → Postgres data: store invoices and payments
- Fastify API → Tax deposits: register deposit routes
- Tax deposits → Postgres data: track liabilities
- Fastify API → Tax filings: register filing routes
- Tax filings → Postgres data: read payroll records
- Fastify API → Obligations calendar: register calendar routes
- Obligations calendar → Postgres data: aggregate obligations
- Change requests → Notification outbox: enqueue notices
- Contractor workflow → Notification outbox: enqueue notices
- Notification outbox → SMTP service: send email
- Legacy accounting DB → Legacy importer: import history
- Legacy importer → Postgres data: write migrated data