-
Notifications
You must be signed in to change notification settings - Fork 0
feat/invoice automation notifications docs #1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Adjanour
wants to merge
3
commits into
master
Choose a base branch
from
feat/invoice-automation-notifications-docs
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| # Waybill System | ||
|
|
||
| Operational waybill, rider, shift, proof-of-delivery, billing, and invoice automation system for field delivery teams. | ||
|
|
||
| ## What This Repo Contains | ||
|
|
||
| - [apps/frontend](/home/bernard/Work/way-bills/apps/frontend): React/Vite operations UI | ||
| - [apps/backend](/home/bernard/Work/way-bills/apps/backend): Hono API, worker, migrations, PDF generation, email delivery | ||
| - [deploy](/home/bernard/Work/way-bills/deploy): Docker, VPS, Caddy, backup, and deployment helpers | ||
| - [docs](/home/bernard/Work/way-bills/docs): product, architecture, and operations documentation | ||
|
|
||
| ## System At A Glance | ||
|
|
||
| The platform supports: | ||
|
|
||
| - rider-led waybill creation and batch dispatch | ||
| - recipient proof of delivery with signature capture | ||
| - historical/manual delivery backfill with receipt-photo evidence | ||
| - rider shift check-in, checkout, and handover trail | ||
| - weekly billing and invoice generation | ||
| - automatic invoice email sending | ||
| - in-app notifications for handovers, failed deliveries, and invoice events | ||
|
|
||
| ## Architecture | ||
|
|
||
| Start here for the top-level view: | ||
|
|
||
| - [Architecture Overview](/home/bernard/Work/way-bills/docs/architecture.md) | ||
|
|
||
| Deployment and operations: | ||
|
|
||
| - [Deployment Guide](/home/bernard/Work/way-bills/deploy/README.md) | ||
| - [Operations Runbook](/home/bernard/Work/way-bills/docs/ops-runbook.md) | ||
| - [Role Guide](/home/bernard/Work/way-bills/docs/role-guide.md) | ||
| - [API Reference](/home/bernard/Work/way-bills/docs/api-reference.md) | ||
|
|
||
| ## Workspace Commands | ||
|
|
||
| Install dependencies from the repo root: | ||
|
|
||
| ```bash | ||
| bun install | ||
| ``` | ||
|
|
||
| Run the frontend and backend locally: | ||
|
|
||
| ```bash | ||
| bun run dev | ||
| ``` | ||
|
|
||
| Useful root commands: | ||
|
|
||
| ```bash | ||
| bun run dev | ||
| bun run build:frontend | ||
| bun run test:backend | ||
| bun run typecheck:backend | ||
| bun run typecheck:frontend | ||
| ``` | ||
|
|
||
| Useful workspace commands: | ||
|
|
||
| ```bash | ||
| bun run --cwd apps/backend test | ||
| bun run --cwd apps/backend db:migrate | ||
| bun run --cwd apps/frontend test | ||
| bun run --cwd apps/frontend build | ||
| ``` | ||
|
|
||
| ## Local Preview | ||
|
|
||
| For a Docker-based local stack: | ||
|
|
||
| ```bash | ||
| cp deploy/backend.local.env.example deploy/backend.local.env | ||
| cp deploy/compose.local.env.example deploy/compose.local.env | ||
| bash deploy/local-preview.sh up | ||
| ``` | ||
|
|
||
| That gives you: | ||
|
|
||
| - frontend: `http://localhost:3000` | ||
| - backend: `http://localhost:3001` | ||
| - local Postgres: `127.0.0.1:54329` | ||
|
|
||
| ## Production Shape | ||
|
|
||
| Production is designed for: | ||
|
|
||
| - Docker Compose on your VPS | ||
| - host-level Caddy as the public reverse proxy | ||
| - PostgreSQL on the VPS or reachable over Docker networking | ||
| - Cloudflare R2 for uploads and generated document storage | ||
| - a separate `backend-worker` service for invoice automation | ||
|
|
||
| ## Main Runtime Components | ||
|
|
||
| - `frontend`: user interface for admin, ops, and riders | ||
| - `backend`: authenticated API for waybills, shifts, billing, PDFs, notifications, and users | ||
| - `backend-worker`: scheduled invoice generation and automatic email sending | ||
| - `postgres`: primary relational datastore | ||
| - `r2`: object storage for receipts, signatures, profile images, and PDFs | ||
|
|
||
| ## Important Notes | ||
|
|
||
| - database migrations live under [apps/backend/drizzle](/home/bernard/Work/way-bills/apps/backend/drizzle) | ||
| - invoice automation and email delivery depend on backend env configuration | ||
| - notifications, worker health, and automation monitor depend on the latest schema | ||
|
|
||
| If you are setting up or updating the system, apply migrations after pulling new changes: | ||
|
|
||
| ```bash | ||
| bun run --cwd apps/backend db:migrate | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,48 @@ | ||
| To install dependencies: | ||
| ```sh | ||
| bun install | ||
| ``` | ||
| # Backend | ||
|
|
||
| This workspace contains the Hono API, background worker, migrations, PDF generation, notification logic, and invoice automation for the Waybill System. | ||
|
|
||
| ## Main Responsibilities | ||
|
|
||
| - authentication and session cookies | ||
| - user, rider, and client management | ||
| - waybill lifecycle rules | ||
| - proof-of-delivery creation | ||
| - shift and handover audit trail | ||
| - reports and billing | ||
| - invoice generation and email delivery | ||
| - notification generation | ||
| - file storage via Cloudflare R2 | ||
|
|
||
| ## Main Entry Points | ||
|
|
||
| - API server: [src/index.ts](/home/bernard/Work/way-bills/apps/backend/src/index.ts) | ||
| - worker: [src/worker.ts](/home/bernard/Work/way-bills/apps/backend/src/worker.ts) | ||
| - worker health: [src/worker-health.ts](/home/bernard/Work/way-bills/apps/backend/src/worker-health.ts) | ||
| - schema: [src/db/schema.ts](/home/bernard/Work/way-bills/apps/backend/src/db/schema.ts) | ||
|
Comment on lines
+19
to
+22
|
||
|
|
||
| To run: | ||
| ```sh | ||
| bun run dev | ||
| ## Commands | ||
|
|
||
| From the repo root: | ||
|
|
||
| ```bash | ||
| bun run --cwd apps/backend dev | ||
| bun run --cwd apps/backend test | ||
| bun run --cwd apps/backend typecheck | ||
| bun run --cwd apps/backend build | ||
| bun run --cwd apps/backend db:generate | ||
| bun run --cwd apps/backend db:migrate | ||
| ``` | ||
|
|
||
| open http://localhost:3000 | ||
| ## Important Folders | ||
|
|
||
| - `src/routes`: API route handlers | ||
| - `src/lib`: business logic and helpers | ||
| - `src/db`: DB client, schema, seed, admin bootstrap | ||
| - `drizzle`: generated SQL migrations and metadata | ||
|
|
||
| ## Related Docs | ||
|
|
||
| - [Root README](/home/bernard/Work/way-bills/README.md) | ||
| - [Architecture Overview](/home/bernard/Work/way-bills/docs/architecture.md) | ||
| - [Deployment Guide](/home/bernard/Work/way-bills/deploy/README.md) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| CREATE TYPE "public"."invoice_email_status" AS ENUM('not_sent', 'queued', 'sent', 'failed');--> statement-breakpoint | ||
| CREATE TYPE "public"."invoice_source" AS ENUM('manual', 'automatic');--> statement-breakpoint | ||
| ALTER TABLE "invoices" ADD COLUMN "source" "invoice_source" DEFAULT 'manual' NOT NULL;--> statement-breakpoint | ||
| ALTER TABLE "invoices" ADD COLUMN "email_status" "invoice_email_status" DEFAULT 'not_sent' NOT NULL;--> statement-breakpoint | ||
| ALTER TABLE "invoices" ADD COLUMN "email_sent_at" timestamp with time zone;--> statement-breakpoint | ||
| ALTER TABLE "invoices" ADD COLUMN "email_delivery_attempts" integer DEFAULT 0 NOT NULL;--> statement-breakpoint | ||
| ALTER TABLE "invoices" ADD COLUMN "last_email_error" text;--> statement-breakpoint | ||
| CREATE UNIQUE INDEX "invoices_client_period_unique" ON "invoices" USING btree ("client_id","period_start","period_end"); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| CREATE TYPE "public"."notification_type" AS ENUM('shift_handover_pending', 'failed_delivery', 'invoice_ready', 'invoice_email_failed');--> statement-breakpoint | ||
| CREATE TABLE "notifications" ( | ||
| "id" text PRIMARY KEY NOT NULL, | ||
| "user_id" text NOT NULL, | ||
| "type" "notification_type" NOT NULL, | ||
| "title" text NOT NULL, | ||
| "message" text NOT NULL, | ||
| "link_path" text, | ||
| "event_key" text, | ||
| "read_at" timestamp with time zone, | ||
| "created_at" timestamp with time zone DEFAULT now() NOT NULL, | ||
| "updated_at" timestamp with time zone DEFAULT now() NOT NULL | ||
| ); | ||
| --> statement-breakpoint | ||
| ALTER TABLE "notifications" ADD CONSTRAINT "notifications_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint | ||
| CREATE INDEX "notifications_user_id_idx" ON "notifications" USING btree ("user_id");--> statement-breakpoint | ||
| CREATE INDEX "notifications_read_at_idx" ON "notifications" USING btree ("read_at");--> statement-breakpoint | ||
| CREATE INDEX "notifications_created_at_idx" ON "notifications" USING btree ("created_at");--> statement-breakpoint | ||
| CREATE UNIQUE INDEX "notifications_user_event_key_unique" ON "notifications" USING btree ("user_id","event_key"); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| CREATE TABLE "automation_job_statuses" ( | ||
| "job_name" text PRIMARY KEY NOT NULL, | ||
| "enabled" boolean DEFAULT false NOT NULL, | ||
| "running" boolean DEFAULT false NOT NULL, | ||
| "interval_minutes" integer DEFAULT 15 NOT NULL, | ||
| "lookback_weeks" integer DEFAULT 8 NOT NULL, | ||
| "last_run_started_at" timestamp with time zone, | ||
| "last_run_finished_at" timestamp with time zone, | ||
| "last_success_at" timestamp with time zone, | ||
| "last_failure_at" timestamp with time zone, | ||
| "last_error" text, | ||
| "last_invoice_summary" text, | ||
| "last_email_summary" text, | ||
| "last_email_failure_at" timestamp with time zone, | ||
| "last_email_error" text, | ||
| "updated_at" timestamp with time zone DEFAULT now() NOT NULL | ||
| ); | ||
| --> statement-breakpoint | ||
| CREATE INDEX "automation_job_statuses_updated_at_idx" ON "automation_job_statuses" USING btree ("updated_at"); |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This README uses absolute local filesystem paths in links (e.g.
/home/bernard/Work/way-bills/...), which will be broken for anyone not on that machine. Please convert these to repo-relative links (e.g./apps/frontend,/docs/architecture.md) so they render correctly on GitHub.