# cognisutra/cdocsign architecture

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

- Interactive diagram: https://gitdiagram.com/cognisutra/cdocsign
- Repository: https://github.com/cognisutra/cdocsign

## Overview

#### Purpose and Runtime
CDocsSign is a lightweight PHP e-signature SaaS: users upload PDFs, configure recipients, collect public signatures, and produce signed PDFs with audit certificates. It runs under PHP 8.1+ (README targets 8.5) behind Apache/Nginx rewrite rules or PHP’s built-in server, with MySQL/MariaDB, PDO, and GD. Primary web root and route handlers are in `public/`; shared application logic is in `src/`.

Paths: `public/index.php`, `public/.htaccess`, `src/db.php`

#### Request Routing and Role Boundaries
Each PHP page is a route/controller. Public routes cover onboarding, public signing, and tracking; authenticated workspace routes manage a customer’s documents; administrator routes manage the whole platform. URL rewrite rules support clean/admin aliases, while physical admin wrappers preserve `/admin/...` paths. Session-based role guards separate `user` and `admin` access, including admin impersonation.

Paths: `public/sign.php`, `public/home.php`, `public/admin.php`, `src/helpers.php`, `src/auth.php`

#### Identity, Sessions, and Notifications
Authentication supports password login, email OTP, password reset, and distinct admin login. Core auth logic establishes sessions and applies RBAC; OTP and reset flows are separate service concerns. Mail dispatch uses SMTP or a Resend HTTP API fallback, with local logging during development. CSRF checks and password hashing are shared security controls.

Paths: `public/login.php`, `public/admin_login.php`, `public/verify.php`, `src/auth.php`, `src/otp.php`, `src/mailer.php`

#### Envelope Lifecycle
An envelope is the central aggregate: it belongs to a user, references an uploaded PDF, has recipients/tokens, status, expiry/reminders, and optional final signed output. Creation accepts document upload and recipient mapping; public signer links use recipient tokens; signer actions advance recipient/envelope state. Templates provide reusable document setup, while reminder processing is a background/cron-oriented service.

Paths: `public/new_envelope.php`, `public/envelope.php`, `public/sign.php`, `src/envelope.php`, `src/template.php`, `src/send_reminders.php`

#### Signing, PDF Assembly, and Protected Files
The signing page captures drawn or typed signatures in the browser. Signature assets and PDFs are stored outside the public web root; downloads are mediated through an authorization/token-checking stream endpoint. Once recipients complete, the PDF service uses vendored FPDF/FPDI to import the original document, place signatures, and append an audit certificate.

Paths: `public/sign.php`, `public/file.php`, `src/pdf.php`, `lib/fpdf/fpdf.php`, `lib/fpdi-src/Fpdi.php`

#### Persistence and Audit Boundary
MySQL/MariaDB is the system of record. The relational schema models users/admins, envelopes, recipients, audit events, templates, versions, resets, payments, login history, and settings, with InnoDB foreign keys. PDO prepared queries isolate persistence access. Every envelope transition is recorded as an audit event, supporting operational views and PDF certification.

Paths: `schema.sql`, `schema_upgrade.sql`, `src/db.php`, `src/audit.php`

#### Administration, Plans, and Operations
The admin console provides cross-tenant user, envelope, template, audit, analytics, finance, and settings views. Customer billing/upgrade pages expose plans and Razorpay checkout simulation; payments are persisted for reporting. System settings control maintenance, quotas, and upload limits, forming an operational control plane rather than customer workspace behavior.

Paths: `public/dashboard.php`, `public/users.php`, `public/audit_logs.php`, `public/settings.php`, `public/billing.php`, `public/upgrade.php`

Main entry points: [`src/envelope.php`](https://github.com/cognisutra/cdocsign/blob/main/src/envelope.php) (Envelope lifecycle), [`src/db.php`](https://github.com/cognisutra/cdocsign/blob/main/src/db.php) (PDO access layer), [`src/auth.php`](https://github.com/cognisutra/cdocsign/blob/main/src/auth.php) (Auth & RBAC), [`public/index.php`](https://github.com/cognisutra/cdocsign/blob/main/public/index.php) (Front controller & rewrites)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web routes"]
  node_front["Front controller &amp; rewrites<br/>PHP entrypoint<br/>[index.php]"]
  node_auth_routes["Login &amp; verification<br/>auth routes<br/>[login.php]"]
  node_workspace["Workspace routes<br/>user controllers<br/>[home.php]"]
  node_envelope_create["Envelope creation<br/>upload controller<br/>[new_envelope.php]"]
  node_signing["Public signing<br/>signer controller<br/>[sign.php]"]
  node_file_delivery["Protected download<br/>file controller<br/>[file.php]"]
end

subgraph group_core["Application services"]
  node_auth{{"Auth &amp; RBAC<br/>security service<br/>[auth.php]"}}
  node_otp["OTP &amp; reset flow<br/>identity service<br/>[otp.php]"]
  node_mailer["Mail delivery<br/>notification service<br/>[mailer.php]"]
  node_envelopes["Envelope lifecycle<br/>domain service<br/>[envelope.php]"]
  node_templates["Templates<br/>domain service<br/>[template.php]"]
  node_pdf["PDF assembly<br/>document service<br/>[pdf.php]"]
  node_audit["Audit trail<br/>audit service<br/>[audit.php]"]
  node_fpdi["FPDF / FPDI<br/>PDF library<br/>[Fpdi.php]"]
end

subgraph group_data["Persistence and files"]
  node_database[("MySQL / MariaDB<br/>relational store<br/>[schema.sql]")]
  node_pdo["PDO access layer<br/>persistence adapter<br/>[db.php]"]
  node_protected_files["Protected PDFs &amp; signatures<br/>file storage"]
end

subgraph group_ops["Administration and operations"]
  node_admin["Admin console<br/>admin controllers<br/>[admin.php]"]
  node_billing["Plans &amp; payments<br/>billing controllers<br/>[billing.php]"]
  node_reminders["Reminder processor<br/>cron service<br/>[send_reminders.php]"]
end

node_front -->|"routes"| node_auth_routes
node_front -->|"routes"| node_workspace
node_front -->|"public signer link"| node_signing
node_auth_routes -->|"authenticates"| node_auth
node_auth_routes -->|"verifies / resets"| node_otp
node_otp -->|"sends codes"| node_mailer
node_workspace -->|"user guard"| node_auth
node_workspace -->|"manages"| node_envelopes
node_envelope_create -->|"creates"| node_envelopes
node_envelope_create -->|"stores upload"| node_protected_files
node_envelopes -.->|"uses setup"| node_templates
node_signing -->|"token-based action"| node_envelopes
node_signing -->|"stores signature"| node_protected_files
node_envelopes -->|"on completion"| node_pdf
node_pdf -->|"imports PDF"| node_fpdi
node_pdf -->|"writes signed PDF"| node_protected_files
node_envelopes -->|"records transitions"| node_audit
node_file_delivery -->|"authorizes"| node_auth
node_file_delivery -->|"streams"| node_protected_files
node_envelopes -->|"persists"| node_pdo
node_audit -->|"persists events"| node_pdo
node_pdo -->|"prepared queries"| node_database
node_admin -->|"admin guard"| node_auth
node_admin -->|"operates across tenants"| node_pdo
node_billing -->|"records payments"| node_pdo
node_reminders -->|"finds pending work"| node_envelopes
node_reminders -->|"sends reminders"| node_mailer

click node_front "https://github.com/cognisutra/cdocsign/blob/main/public/index.php"
click node_auth_routes "https://github.com/cognisutra/cdocsign/blob/main/public/login.php"
click node_workspace "https://github.com/cognisutra/cdocsign/blob/main/public/home.php"
click node_envelope_create "https://github.com/cognisutra/cdocsign/blob/main/public/new_envelope.php"
click node_signing "https://github.com/cognisutra/cdocsign/blob/main/public/sign.php"
click node_file_delivery "https://github.com/cognisutra/cdocsign/blob/main/public/file.php"
click node_auth "https://github.com/cognisutra/cdocsign/blob/main/src/auth.php"
click node_otp "https://github.com/cognisutra/cdocsign/blob/main/src/otp.php"
click node_mailer "https://github.com/cognisutra/cdocsign/blob/main/src/mailer.php"
click node_envelopes "https://github.com/cognisutra/cdocsign/blob/main/src/envelope.php"
click node_templates "https://github.com/cognisutra/cdocsign/blob/main/src/template.php"
click node_pdf "https://github.com/cognisutra/cdocsign/blob/main/src/pdf.php"
click node_audit "https://github.com/cognisutra/cdocsign/blob/main/src/audit.php"
click node_database "https://github.com/cognisutra/cdocsign/blob/main/schema.sql"
click node_pdo "https://github.com/cognisutra/cdocsign/blob/main/src/db.php"
click node_admin "https://github.com/cognisutra/cdocsign/blob/main/public/admin.php"
click node_billing "https://github.com/cognisutra/cdocsign/blob/main/public/billing.php"
click node_reminders "https://github.com/cognisutra/cdocsign/blob/main/src/send_reminders.php"
click node_fpdi "https://github.com/cognisutra/cdocsign/blob/main/lib/fpdi-src/Fpdi.php"

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_front,node_auth_routes,node_workspace,node_envelope_create,node_signing,node_file_delivery toneBlue
class node_auth,node_otp,node_mailer,node_envelopes,node_templates,node_pdf,node_audit,node_fpdi toneAmber
class node_database,node_pdo,node_protected_files toneMint
class node_admin,node_billing,node_reminders toneRose
```

## Components

### Web routes

PHP page controllers and browser-facing flows.

- [Front controller & rewrites](https://github.com/cognisutra/cdocsign/blob/main/public/index.php): PHP entrypoint · Routes clean URLs to page controllers. · `public/index.php`
- [Login & verification](https://github.com/cognisutra/cdocsign/blob/main/public/login.php): auth routes · Customer login, admin login, and OTP verification pages. · `public/login.php`
- [Workspace routes](https://github.com/cognisutra/cdocsign/blob/main/public/home.php): user controllers · Authenticated customers create and manage envelopes. · `public/home.php`
- [Envelope creation](https://github.com/cognisutra/cdocsign/blob/main/public/new_envelope.php): upload controller · Accepts PDFs and recipient configuration. · `public/new_envelope.php`
- [Public signing](https://github.com/cognisutra/cdocsign/blob/main/public/sign.php): signer controller · Captures drawn or typed recipient signatures. · `public/sign.php`
- [Protected download](https://github.com/cognisutra/cdocsign/blob/main/public/file.php): file controller · Streams files after authorization or token checks. · `public/file.php`

### Application services

Shared domain, security, and delivery logic.

- [Auth & RBAC](https://github.com/cognisutra/cdocsign/blob/main/src/auth.php): security service · Sessions, role guards, impersonation, CSRF, and password security. · `src/auth.php`
- [OTP & reset flow](https://github.com/cognisutra/cdocsign/blob/main/src/otp.php): identity service · Manages email OTP and password recovery. · `src/otp.php`
- [Mail delivery](https://github.com/cognisutra/cdocsign/blob/main/src/mailer.php): notification service · Uses SMTP, Resend fallback, or local logging. · `src/mailer.php`
- [Envelope lifecycle](https://github.com/cognisutra/cdocsign/blob/main/src/envelope.php): domain service · Manages recipients, tokens, status, expiry, and completion. · `src/envelope.php`
- [Templates](https://github.com/cognisutra/cdocsign/blob/main/src/template.php): domain service · Provides reusable document setup. · `src/template.php`
- [PDF assembly](https://github.com/cognisutra/cdocsign/blob/main/src/pdf.php): document service · Places signatures and appends audit certificates. · `src/pdf.php`
- [Audit trail](https://github.com/cognisutra/cdocsign/blob/main/src/audit.php): audit service · Records envelope transitions for operations and certification. · `src/audit.php`
- [FPDF / FPDI](https://github.com/cognisutra/cdocsign/blob/main/lib/fpdi-src/Fpdi.php): PDF library · Imports original PDFs for final document generation. · `lib/fpdi-src/Fpdi.php`

### Persistence and files

System-of-record data and protected artifacts.

- [MySQL / MariaDB](https://github.com/cognisutra/cdocsign/blob/main/schema.sql): relational store · System of record for tenants, envelopes, recipients, payments, and settings. · `schema.sql`
- [PDO access layer](https://github.com/cognisutra/cdocsign/blob/main/src/db.php): persistence adapter · Prepared-query boundary for relational persistence. · `src/db.php`
- **Protected PDFs & signatures**: file storage · Artifacts are stored outside the public web root.

### Administration and operations

Cross-tenant control, billing, and scheduled work.

- [Admin console](https://github.com/cognisutra/cdocsign/blob/main/public/admin.php): admin controllers · Cross-tenant users, envelopes, audits, analytics, and settings. · `public/admin.php`
- [Plans & payments](https://github.com/cognisutra/cdocsign/blob/main/public/billing.php): billing controllers · Plan upgrades and Razorpay checkout simulation. · `public/billing.php`
- [Reminder processor](https://github.com/cognisutra/cdocsign/blob/main/src/send_reminders.php): cron service · Sends reminders for pending envelopes. · `src/send_reminders.php`

## Connections

- Front controller & rewrites → Login & verification: routes
- Front controller & rewrites → Workspace routes: routes
- Front controller & rewrites → Public signing: public signer link
- Login & verification → Auth & RBAC: authenticates
- Login & verification → OTP & reset flow: verifies / resets
- OTP & reset flow → Mail delivery: sends codes
- Workspace routes → Auth & RBAC: user guard
- Workspace routes → Envelope lifecycle: manages
- Envelope creation → Envelope lifecycle: creates
- Envelope creation → Protected PDFs & signatures: stores upload
- Envelope lifecycle → Templates: uses setup
- Public signing → Envelope lifecycle: token-based action
- Public signing → Protected PDFs & signatures: stores signature
- Envelope lifecycle → PDF assembly: on completion
- PDF assembly → FPDF / FPDI: imports PDF
- PDF assembly → Protected PDFs & signatures: writes signed PDF
- Envelope lifecycle → Audit trail: records transitions
- Protected download → Auth & RBAC: authorizes
- Protected download → Protected PDFs & signatures: streams
- Envelope lifecycle → PDO access layer: persists
- Audit trail → PDO access layer: persists events
- PDO access layer → MySQL / MariaDB: prepared queries
- Admin console → Auth & RBAC: admin guard
- Admin console → PDO access layer: operates across tenants
- Plans & payments → PDO access layer: records payments
- Reminder processor → Envelope lifecycle: finds pending work
- Reminder processor → Mail delivery: sends reminders