{"id":47711420,"url":"https://github.com/techmedaddy/payeazie","last_synced_at":"2026-04-02T18:34:28.901Z","repository":{"id":325151267,"uuid":"1099035915","full_name":"techmedaddy/payeazie","owner":"techmedaddy","description":"A payment execution engine focused on idempotency, atomic state transitions, and webhook-safe processing. Designed with ledger-first consistency, worker-driven orchestration, and reconciliation workflows that prevent double charges under concurrency and retries.","archived":false,"fork":false,"pushed_at":"2026-03-21T00:23:36.000Z","size":566,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-21T12:21:12.027Z","etag":null,"topics":["idempotency","nodejs","queue"],"latest_commit_sha":null,"homepage":"https://payeazie.netlify.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/techmedaddy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T13:25:13.000Z","updated_at":"2026-03-21T00:23:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/techmedaddy/payeazie","commit_stats":null,"previous_names":["techmedaddy/payeazie"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/techmedaddy/payeazie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techmedaddy%2Fpayeazie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techmedaddy%2Fpayeazie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techmedaddy%2Fpayeazie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techmedaddy%2Fpayeazie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/techmedaddy","download_url":"https://codeload.github.com/techmedaddy/payeazie/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/techmedaddy%2Fpayeazie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["idempotency","nodejs","queue"],"created_at":"2026-04-02T18:34:28.170Z","updated_at":"2026-04-02T18:34:28.868Z","avatar_url":"https://github.com/techmedaddy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Payeazie\n\nPayeazie is a full-stack payment operations application built around a simple but realistic payment lifecycle: create a payment, process it asynchronously, reconcile long-running states, expose audit history, and give internal operators a controlled way to intervene when something goes wrong.\n\nThe current repository sits between a prototype and a productized internal tool. It has enough operational behavior to model real payment workflows, while still using a mock gateway and local-first infrastructure so the system is easy to run, inspect, and extend.\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/f242554d-65bc-41bf-ab4b-13c0f6ddbeb5\" /\u003e\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/83636615-57bd-4457-9afa-3956698119d3\" /\u003e\n\n\n## What The Project Covers\n\n- Merchant-facing payment creation and tracking\n- Asynchronous charge processing through Redis and BullMQ workers\n- State-machine-based payment transitions with audit logging\n- Refunds with eligibility rules and operator attribution\n- Retry and stuck-payment recovery actions with backend guardrails\n- Internal ops dashboard for all-payments visibility and manual actions\n- Internal gateway/webhook simulator for controlled status changes\n- JWT auth, Google OAuth, forgot-password, and reset-password flows\n- Health and metrics endpoints for basic operational visibility\n\n## Repository Layout\n\n```text\n.\n├── backend/         Fastify API, workers, PostgreSQL access, auth, audit, queues\n├── frontend/        React + Vite UI for merchant and internal operator workflows\n└── README.md        Root project guide\n```\n\nThere is no root-level one-command orchestrator today. The backend and frontend are run separately.\n\n## Tech Stack\n\n### Backend\n\n- Node.js\n- Fastify\n- PostgreSQL via `pg-promise`\n- Redis\n- BullMQ\n- JWT authentication\n- Google OAuth 2.0\n- Nodemailer for password reset email delivery\n- Vitest for tests\n\n### Frontend\n\n- React 19\n- TypeScript\n- Vite\n- React Router\n- Recharts\n- Vitest + Testing Library\n\n## Current Architecture\n\n```mermaid\nflowchart LR\n    UI[\"Frontend UI\u003cbr\u003eReact + Vite\"] --\u003e|REST| API[\"Fastify API\"]\n    UI --\u003e|Navigation| ROUTER[\"Hash Router\"]\n\n    API --\u003e DB[(PostgreSQL)]\n    API --\u003e REDIS[(Redis)]\n    API --\u003e SSE[\"SSE stream endpoint\"]\n    API --\u003e METRICS[\"Health and metrics endpoints\"]\n\n    REDIS --\u003e CHARGE[\"Charge Worker\"]\n    REDIS --\u003e RECON[\"Reconcile Worker\"]\n\n    CHARGE --\u003e GATEWAY[\"Mock Gateway Client\"]\n    RECON --\u003e GATEWAY\n\n    CHARGE --\u003e DB\n    RECON --\u003e DB\n    API --\u003e AUDIT[(payment_audit_log)]\n    CHARGE --\u003e AUDIT\n    RECON --\u003e AUDIT\n```\n\n## Architectural Patterns In Use\n\n### 1. API + worker split\n\nPayment creation returns quickly after persistence and queueing. Gateway interaction happens in background workers rather than inside the request-response path.\n\n### 2. Explicit status lifecycle\n\nPayment states are centralized in the backend and validated through a shared transition model rather than being treated as free-form strings.\n\n### 3. Audit-first transitions\n\nStatus changes are not just updates to the `payments` table. They are paired with audit records that capture actor, source, metadata, and timestamps.\n\n### 4. Recovery as a first-class concern\n\nRetry, reconcile, restart, refund, and simulated gateway updates are treated as explicit operational actions with backend guardrails, not ad hoc UI buttons.\n\n### 5. Role-aware internal surfaces\n\nMerchants primarily see their own payments. Internal operators with `admin` or `ops` roles can access all payments and internal recovery tools.\n\n### 6. Local-first infrastructure\n\nThe stack assumes PostgreSQL and Redis are available locally. The gateway is mocked by default, which keeps the project runnable without third-party payment credentials.\n\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/c29197db-5808-4f8e-b044-2fe09960ca48\" /\u003e\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e5931b80-c8ee-438e-9d6c-cc3dbf148459\" /\u003e\n\n\n## End-To-End Payment Flow\n\n```mermaid\nsequenceDiagram\n    actor User\n    participant FE as Frontend\n    participant API as Fastify API\n    participant DB as PostgreSQL\n    participant Q as BullMQ\n    participant CW as Charge Worker\n    participant GW as Gateway\n    participant AUDIT as Audit Log\n\n    User-\u003e\u003eFE: Create payment\n    FE-\u003e\u003eAPI: POST /api/payments or /api/payments/intents\n    API-\u003e\u003eDB: Insert payment as pending\n    API-\u003e\u003eQ: Enqueue charge job\n    API--\u003e\u003eFE: Payment response\n\n    Q-\u003e\u003eCW: Dequeue charge job\n    CW-\u003e\u003eDB: pending -\u003e processing\n    CW-\u003e\u003eAUDIT: Log automatic transition\n    CW-\u003e\u003eGW: Charge request\n\n    alt gateway success\n        GW--\u003e\u003eCW: succeeded\n        CW-\u003e\u003eDB: Update payment\n        CW-\u003e\u003eAUDIT: Log processing -\u003e succeeded\n    else gateway failure\n        GW--\u003e\u003eCW: failed\n        CW-\u003e\u003eDB: Update payment\n        CW-\u003e\u003eAUDIT: Log processing -\u003e failed\n    end\n\n    FE-\u003e\u003eAPI: GET /api/payments/:paymentId\n    API--\u003e\u003eFE: Rich payment detail with audit + recovery metadata\n```\n\n## Status Model\n\nThe backend lifecycle lives in `backend/src/utils/payment-status.js` and is the source of truth for finality, retryability, refundability, and transition validity.\n\n### Supported statuses\n\n| Status | Meaning |\n| --- | --- |\n| `pending` | Payment exists and is ready to be worked |\n| `processing` | Worker has picked it up or the gateway state is in flight |\n| `succeeded` | Charge completed successfully |\n| `failed` | Charge failed or the payment was returned to a failed outcome |\n| `refunded` | A previously successful payment was refunded |\n\n### Allowed transitions\n\n| From | To |\n| --- | --- |\n| `pending` | `processing`, `failed` |\n| `processing` | `pending`, `succeeded`, `failed` |\n| `succeeded` | `refunded` |\n| `failed` | `pending` |\n| `refunded` | none |\n\n### Final states\n\n- `succeeded`\n- `failed`\n- `refunded`\n\n### Operational guardrails currently enforced\n\n- Refund is only allowed from `succeeded`\n- Retry is only allowed from `failed`\n- Refunded payments cannot transition further\n- Reconcile and restart are aimed at stuck `processing` payments\n- Internal simulator actions are restricted to internal roles\n\n## Manual Actions And Recovery Model\n\nThe application now treats operations support as part of the normal flow, not as an afterthought.\n\n| Action | Intended use | Current backend rule |\n| --- | --- | --- |\n| Refund | Reverse a completed charge | Only `succeeded` payments, reason required |\n| Retry | Reprocess a failed payment | Only `failed` payments, with retry guardrails |\n| Reconcile | Check a long-running processing payment against gateway state | Used for stuck `processing` records with gateway context |\n| Restart | Move a stuck processing payment back into the queue path | Used for stuck `processing` records that need to be requeued |\n| Simulate gateway status | Trigger controlled internal state changes | Internal-only, valid next statuses only |\n\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/fb7a6b03-ea33-476f-bc4d-8b1b44389ea2\" /\u003e\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/1f265e4a-43c6-4078-b41b-b90480ba3643\" /\u003e\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ea10a429-60a3-4497-9cf4-6a0941eaae72\" /\u003e\n\n\n\n\n## Payment Recovery Flow\n\n```mermaid\nflowchart TD\n    P[Payment detail or Ops dashboard] --\u003e S{Current state}\n    S --\u003e|Succeeded| R[Refund]\n    S --\u003e|Failed| RT[Retry]\n    S --\u003e|Processing and stuck| C{Has gateway charge id?}\n    C --\u003e|Yes| REC[Reconcile]\n    C --\u003e|No| RES[Restart]\n\n    R --\u003e A1[Audit log with actor, time, reason, source]\n    RT --\u003e A2[Audit log with actor and source]\n    REC --\u003e A3[Audit log with operator metadata]\n    RES --\u003e A4[Audit log with operator metadata]\n```\n\n## Backend Design\n\n### API surface\n\nThe backend runs as a Fastify server and registers payment, auth, and audit routes under `/api` or `/api/auth`.\n\n#### Health and metrics\n\n- `GET /`\n- `GET /health`\n- `GET /health/detailed`\n- `GET /metrics`\n- `GET /metrics/summary`\n\n#### Auth endpoints\n\n- `POST /api/auth/register`\n- `POST /api/auth/login`\n- `GET /api/auth/me`\n- `POST /api/auth/forgot-password`\n- `POST /api/auth/reset-password`\n- `GET /api/auth/google`\n- `GET /api/auth/google/callback`\n\n#### Payment endpoints\n\n- `GET /api/payments`\n- `GET /api/payments/:paymentId`\n- `POST /api/payments`\n- `POST /api/payments/intents`\n- `GET /api/payments/:paymentId/audit`\n- `GET /api/payments/:paymentId/stream`\n- `POST /api/payments/:paymentId/refund`\n- `POST /api/payments/:paymentId/retry`\n- `POST /api/payments/:paymentId/reconcile`\n- `POST /api/payments/:paymentId/restart`\n- `POST /api/payments/:paymentId/simulate-gateway`\n- `POST /api/payments/reconcile`\n- `POST /api/payments/webhook`\n\n### Backend module responsibilities\n\n| Area | Purpose |\n| --- | --- |\n| `server.js` | Bootstraps env validation, migrations, Fastify plugins, routes, workers, and health/metrics endpoints |\n| `src/api/controllers/` | Request handlers for payments, auth, audit, webhook, and SSE |\n| `src/api/routes/` | Route registration and schema definitions |\n| `src/api/middleware/` | JWT auth, rate limiting, request logging, internal-role enforcement |\n| `src/core/status-transition/` | Central transition engine and audit/event metadata handling |\n| `src/core/orchestrator/` | Payment orchestration helpers that coordinate state and gateway results |\n| `src/db/` and `src/db/models/` | PostgreSQL connection and data access |\n| `src/utils/queue.js` | BullMQ queue helpers and worker creation |\n| `src/workers/` | Charge processing and reconciliation background jobs |\n| `src/utils/payment-status.js` | Shared lifecycle rules |\n| `src/utils/roles.js` | Internal role detection and access helpers |\n\n### Data model shape\n\nAt a high level, the backend revolves around a few core entities:\n\n- `payments`\n  Stores order id, amount, currency, lifecycle status, idempotency key, gateway charge id, and ownership context.\n- `payment_audit_log`\n  Stores status changes and operational actions with metadata, actor, source, and timestamps.\n- `gateway_events`\n  Tracks incoming or simulated gateway events used for reconciliation and webhook handling.\n- `users`\n  Stores login identity, password hash or OAuth-linked account details, and role.\n\n  \u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/b0c3329e-b06f-4ec1-af76-4a74b620ef0f\" /\u003e\n  \u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/6d0d608f-0523-40aa-9799-4adc0aaee453\" /\u003e\n  \u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/8c473cc7-c6a0-48ab-9cca-cbba27008f3c\" /\u003e\n\n\n### Request handling pattern\n\nFor most payment mutations, the request path follows this pattern:\n\n1. Authenticate the user.\n2. Validate payload and route params.\n3. Check ownership or internal-role access.\n4. Load current payment state.\n5. Enforce lifecycle guardrails.\n6. Persist transition or enqueue asynchronous work.\n7. Append audit metadata.\n8. Return a UI-friendly response with status, recovery hints, and context.\n\n### Queue and worker behavior\n\nBullMQ is used for two main background workloads:\n\n- Charge processing\n  Picks up queued payments, moves them to `processing`, calls the gateway client, and finalizes them as `succeeded` or `failed`.\n- Reconciliation\n  Reviews long-running or potentially inconsistent payments and attempts to realign local state with gateway state.\n\nThis split matters because it keeps user-facing API latency separate from gateway timing and creates a clear place for retry/recovery logic.\n\n### Audit and ops metadata\n\nThe audit trail is richer than a simple status history. The current backend records whether a status change was:\n\n- `automatic`\n- `user_triggered`\n- `admin_triggered`\n\nThat metadata is surfaced back to the UI so detail views can explain not just what changed, but how it changed.\n\n## Frontend Design\n\nThe frontend uses React with a hash-based router and a protected-route model for authenticated pages.\n\n### Primary routes\n\n| Route | Purpose |\n| --- | --- |\n| `/#/login` | Email/password sign-in |\n| `/#/register` | User registration |\n| `/#/forgot-password` | Password reset request |\n| `/#/reset-password` | Password reset submission |\n| `/#/dashboard` | Main merchant dashboard |\n| `/#/create` | Create payment screen |\n| `/#/payment/:id` | Detailed payment lifecycle page |\n| `/#/account` | Basic account panel |\n| `/#/ops` | Internal operator dashboard, restricted to `admin` and `ops` |\n\n### Frontend structure\n\n| Area | Purpose |\n| --- | --- |\n| `App.tsx` | Top-level routing and providers |\n| `context/` | Auth state and toast notifications |\n| `components/ProtectedRoute.tsx` | Route-level auth and role gating |\n| `components/ui/Layout.tsx` | Shared shell and navigation |\n| `pages/Dashboard.tsx` | Merchant dashboard with metrics, filters, tables, and recovery visibility |\n| `pages/OpsDashboard.tsx` | Internal view for all payments, stuck queue, failure spikes, and simulator |\n| `pages/PaymentDetails.tsx` | Rich lifecycle detail, audit trail, refund/retry/recovery actions |\n| `services/api.ts` | Shared fetch wrapper, auth token management, retry logic, redirect handling |\n| `services/payments.ts` | Payment API client methods |\n| `hooks/usePaymentDetails.ts` | Normalizes backend detail payload into UI-friendly state |\n| `utils/paymentMetrics.ts` | Shared success/failure/refund/latency storytelling helpers |\n\n### UI model\n\nThe frontend is intentionally not just a CRUD wrapper over the API. It interprets backend state into:\n\n- status badges\n- retry/refund eligibility messages\n- stuck-processing indicators\n- refund summaries and audit context\n- operator-facing manual actions\n- metric narratives such as success rate, failure rate, refund rate, and processing latency\n\n## Auth And Access Model\n\n```mermaid\nflowchart TD\n    U[User] --\u003e L[Login or register]\n    U --\u003e G[Google OAuth]\n    U --\u003e F[Forgot password]\n\n    L --\u003e JWT[JWT token issued]\n    G --\u003e JWT\n    F --\u003e RP[Reset password]\n    RP --\u003e JWT\n\n    JWT --\u003e PR[Protected routes]\n    PR --\u003e DASH[Merchant dashboard]\n    PR --\u003e PAY[Payment details]\n    PR --\u003e ACC[Account]\n\n    PR --\u003e OPS{Role is admin or ops?}\n    OPS --\u003e|Yes| O1[Ops dashboard]\n    OPS --\u003e|No| O2[Ops route blocked]\n```\n\n### Auth behavior currently implemented\n\n- Email/password registration and login\n- JWT-based protected API access\n- Google OAuth callback flow\n- Forgot-password request and reset-password submission\n- Session-expiry handling in the frontend API client\n- Inline feedback and auth-related toast support\n- Account page with name, email, and role\n\n## Dashboards And Operational Visibility\n\n### Merchant dashboard\n\nThe merchant dashboard is the main day-to-day surface. It currently includes:\n\n- search and status/date filtering\n- gross and net payment metrics\n- refund-aware metrics\n- charts for payment volume\n- recent activity\n- payment table\n- processing and stuck-payment visibility\n- performance storytelling based on current payment data\n\n### Ops dashboard\n\nThe ops dashboard is designed for internal support and operational recovery. It currently includes:\n\n- all-payments visibility across users\n- stuck processing queue\n- failed payments queue\n- failure spike monitor\n- manual retry, reconcile, and restart actions\n- gateway/webhook simulator panel\n- outcome metrics and performance story\n\n## Metrics And Observability\n\n### HTTP endpoints\n\n- `/health`\n  Lightweight process health\n- `/health/detailed`\n  Process health plus PostgreSQL and Redis connectivity\n- `/metrics`\n  Raw metric payload\n- `/metrics/summary`\n  Aggregated summary payload\n\n### UI-facing operational metrics\n\nThe frontend now tells a more complete story than simple counts:\n\n- success rate\n- failure rate\n- refund rate\n- average processing latency\n\nThese are calculated from available payment data rather than inferred from gateway internals that do not exist in the current implementation.\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/3b40fb3e-1357-4f5b-8aa8-b69adbdd0ae3\" /\u003e\n\u003cimg width=\"1913\" height=\"987\" alt=\"image\" src=\"https://github.com/user-attachments/assets/8da4b355-4ddd-42af-9704-669bd33a455d\" /\u003e\n\n\n## Running The Project Locally\n\n### Prerequisites\n\n- Node.js 18+ recommended\n- PostgreSQL\n- Redis\n\n### 1. Start the backend\n\n```bash\ncd backend\nnpm install\ncp .env.example .env\n```\n\nUpdate `.env` with at least:\n\n- `DATABASE_URL`\n- `REDIS_URL`\n- `JWT_SECRET`\n\nOptional but useful for full auth coverage:\n\n- Google OAuth values\n- SMTP values for password reset email delivery\n- `FRONTEND_URL`\n\nInitialize the database:\n\n```bash\nnpm run db:setup\n```\n\nStart the API and workers:\n\n```bash\nnpm start\n```\n\nBy default the backend runs on `http://localhost:3467`.\n\n### 2. Start the frontend\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\nThe frontend runs on Vite's local dev server, typically `http://localhost:5173`.\n\nIf needed, point the frontend at a custom API origin with:\n\n```bash\nVITE_API_URL=http://localhost:3467\n```\n\nBecause the app uses `HashRouter`, the common authenticated entrypoint is:\n\n```text\nhttp://localhost:5173/#/dashboard\n```\n\n## Testing\n\n### Backend\n\nRun the backend test suite:\n\n```bash\ncd backend\nnpm test\n```\n\nUseful backend scripts:\n\n```bash\nnpm run test:watch\nnpm run test:coverage\nnpm run test:ui\n```\n\n### Frontend\n\nRun the frontend test suite:\n\n```bash\ncd frontend\nnpm test\n```\n\nUseful frontend scripts:\n\n```bash\nnpm run test:ui\nnpm run test:coverage\nnpm run build\n```\n\n## Recommended Reading Order In The Codebase\n\nIf you are trying to understand the project quickly, this order works well:\n\n1. `backend/server.js`\n2. `backend/src/api/routes/payment.routes.js`\n3. `backend/src/api/controllers/payment.controller.js`\n4. `backend/src/core/status-transition/status-transition.service.js`\n5. `backend/src/utils/payment-status.js`\n6. `backend/src/workers/charge.worker.js`\n7. `backend/src/workers/reconcile.worker.js`\n8. `frontend/App.tsx`\n9. `frontend/pages/Dashboard.tsx`\n10. `frontend/pages/OpsDashboard.tsx`\n11. `frontend/pages/PaymentDetails.tsx`\n12. `frontend/services/payments.ts`\n\n## What Is Real Versus What Is Simulated\n\nThis repository intentionally mixes real application patterns with a simulated payment provider.\n\n### Real application behavior\n\n- asynchronous queue-based processing\n- lifecycle validation\n- recovery actions and safety rules\n- audit logging\n- role-aware ops tooling\n- auth flows\n- frontend/backend integration patterns\n\n### Simulated or local-only behavior\n\n- payment gateway responses are mocked\n- internal simulator can drive gateway-like status changes on demand\n- local infrastructure is expected for PostgreSQL and Redis\n\nThat balance makes the project useful for engineering work, operational design, and UI/backend iteration without pretending to be a fully integrated commercial payment platform.\n\n## Current Boundaries And Tradeoffs\n\n- The default gateway integration is mock-first, not a live processor integration.\n- There is no root-level Docker or Compose workflow in the repository today.\n- The frontend currently uses hash-based routing rather than server-backed SPA routing.\n- Local development expects PostgreSQL and Redis to be available.\n- Some backend tests are easier to run when local infrastructure is present.\n- Frontend production builds may show a large-chunk warning; the app still builds successfully.\n\n## Deployment Notes\n\nDeployment details are documented separately in:\n\n- `backend/DEPLOYMENT.md`\n\nThis root README focuses on how the codebase works today rather than prescribing a single hosting model.\n\n## Summary\n\nPayeazie currently functions as a practical payment operations system with:\n\n- a merchant-facing dashboard\n- an internal ops console\n- asynchronous payment processing\n- auditable lifecycle management\n- controlled recovery and refund tooling\n- auth flows needed for a real multi-user application\n\nIt is detailed enough to reason about operational payment behavior, but still compact enough to run and evolve as a local full-stack project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechmedaddy%2Fpayeazie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechmedaddy%2Fpayeazie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechmedaddy%2Fpayeazie/lists"}