# anthony20602/mokhtar_forms_app architecture

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

- Interactive diagram: https://gitdiagram.com/anthony20602/mokhtar_forms_app
- Repository: https://github.com/anthony20602/mokhtar_forms_app

## Overview

Mokhtar Forms is a local-network registry and certificate-issuing web app for a mukhtar’s office. Staff search and maintain villagers, optionally import people from Excel, then create, save, reopen, and print one of 15 forms; documents receive yearly serial numbers. The map follows the browser/API/service/database boundaries and highlights import, form definitions, settings, and printing. README capability descriptions and the source index support some unsampled route links; those links are marked dashed where implementation details were not excerpted.

Main entry points: [`src/app/api`](https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/app/api) (API routes), [`src/frontend/api/client.ts`](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/api/client.ts) (API client), [`src/backend/database/db.ts`](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/database/db.ts) (PostgreSQL access), [`src/backend/services/documents.ts`](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/documents.ts) (Saved documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_webui["Office pages"]
  node_personui["People screens"]
  node_docui["Document editor<br/>[DocumentEditor.tsx]"]
  node_importui["Excel import UI<br/>[PersonImport.tsx]"]
  node_settingsui["Settings form<br/>[SettingsForm.tsx]"]
  node_clientapi["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_routes["API routes"]
  node_http["HTTP errors<br/>[http.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
  node_auth["Password sessions<br/>[auth.ts]"]
end

subgraph group_domain["Registry and documents"]
  node_persons["People registry<br/>[persons.ts]"]
  node_import["Excel import<br/>[personImport.ts]"]
  node_importrules["Import rules"]
  node_documents["Saved documents<br/>[documents.ts]"]
  node_settings["Office settings<br/>[settings.ts]"]
  node_arabic["Arabic normalization<br/>[arabic.ts]"]
end

subgraph group_forms["Forms and printing"]
  node_formdefs["Form catalog<br/>[registry.ts]"]
  node_letter["Certificate letters<br/>[letter.ts]"]
  node_residence["Residence template<br/>[residence.ts]"]
  node_printui["Print controls<br/>[PrintToolbar.tsx]"]
  node_printing["PDF and printers<br/>[printing.ts]"]
end

subgraph group_storage["Persistence"]
  node_db[("PostgreSQL access<br/>[db.ts]")]
end

node_staff(("Office staff"))
node_postgres[("PostgreSQL")]

node_staff -->|"uses"| node_webui
node_webui -.->|"opens"| node_personui
node_webui -.->|"opens"| node_docui
node_personui -->|"requests"| node_clientapi
node_docui -->|"requests"| node_clientapi
node_importui -.->|"uploads"| node_clientapi
node_settingsui -->|"requests"| node_clientapi
node_clientapi -->|"fetches"| node_routes
node_routes -->|"wraps handlers"| node_http
node_routes -->|"validates input"| node_validation
node_routes -->|"calls"| node_documents
node_routes -->|"calls"| node_persons
node_routes -->|"calls"| node_import
node_routes -->|"calls"| node_settings
node_routes -->|"checks credentials"| node_auth
node_import -->|"uses rules"| node_importrules
node_persons -->|"normalizes names"| node_arabic
node_documents -->|"normalizes search"| node_arabic
node_routes -->|"requests print or PDF"| node_printing
node_routes -->|"loads print document"| node_documents
node_printui -.->|"requests print"| node_routes
node_formdefs -->|"defines letters"| node_letter
node_formdefs -->|"defines template"| node_residence
node_docui -->|"selects form"| node_formdefs
node_printing -->|"creates print token"| node_auth
node_persons -->|"queries"| node_db
node_documents -->|"queries and writes"| node_db
node_import -->|"reads and imports"| node_db
node_settings -->|"queries"| node_db
node_db -->|"connects"| node_postgres
node_staff -.->|"imports workbook"| node_importui
node_staff -.->|"prints or downloads"| node_printui

click node_webui "https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/app/(app)"
click node_personui "https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/frontend/components/persons"
click node_docui "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/documents/DocumentEditor.tsx"
click node_importui "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/persons/PersonImport.tsx"
click node_settingsui "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/settings/SettingsForm.tsx"
click node_clientapi "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/api/client.ts"
click node_routes "https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/app/api"
click node_http "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/api/http.ts"
click node_validation "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/api/validation.ts"
click node_auth "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/auth/auth.ts"
click node_persons "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/persons.ts"
click node_import "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/personImport.ts"
click node_importrules "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/personImportRules.ts"
click node_documents "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/documents.ts"
click node_settings "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/settings.ts"
click node_formdefs "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/registry.ts"
click node_letter "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/letter.ts"
click node_residence "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/residence.ts"
click node_printui "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/documents/PrintToolbar.tsx"
click node_printing "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/printing.ts"
click node_arabic "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/arabic.ts"
click node_db "https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/database/db.ts"

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_webui,node_personui,node_docui,node_importui,node_settingsui,node_clientapi toneBlue
class node_routes,node_http,node_validation,node_auth,node_postgres toneAmber
class node_persons,node_import,node_importrules,node_documents,node_settings,node_arabic toneMint
class node_formdefs,node_letter,node_residence,node_printui,node_printing toneRose
class node_db,node_staff toneIndigo
```

## Components

### Browser experience

- [Office pages](https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/app/(app)): `src/app/(app)`
- [People screens](https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/frontend/components/persons): `src/frontend/components/persons`
- [Document editor](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/documents/DocumentEditor.tsx): `src/frontend/components/documents/DocumentEditor.tsx`
- [Excel import UI](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/persons/PersonImport.tsx): `src/frontend/components/persons/PersonImport.tsx`
- [Settings form](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/settings/SettingsForm.tsx): `src/frontend/components/settings/SettingsForm.tsx`
- [API client](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/api/client.ts): `src/frontend/api/client.ts`

### API and access

- [API routes](https://github.com/anthony20602/mokhtar_forms_app/tree/main/src/app/api): `src/app/api`
- [HTTP errors](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/api/http.ts): `src/backend/api/http.ts`
- [Input validation](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/api/validation.ts): `src/backend/api/validation.ts`
- [Password sessions](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/auth/auth.ts): `src/backend/auth/auth.ts`

### Registry and documents

- [People registry](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/persons.ts): `src/backend/services/persons.ts`
- [Excel import](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/personImport.ts): `src/backend/services/personImport.ts`
- [Import rules](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/personImportRules.ts): `src/backend/services/personImportRules.ts`
- [Saved documents](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/documents.ts): `src/backend/services/documents.ts`
- [Office settings](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/settings.ts): `src/backend/services/settings.ts`
- [Arabic normalization](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/arabic.ts): `src/shared/arabic.ts`

### Forms and printing

- [Form catalog](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/registry.ts): `src/shared/forms/registry.ts`
- [Certificate letters](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/letter.ts): `src/shared/forms/letter.ts`
- [Residence template](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/shared/forms/residence.ts): `src/shared/forms/residence.ts`
- [Print controls](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/frontend/components/documents/PrintToolbar.tsx): `src/frontend/components/documents/PrintToolbar.tsx`
- [PDF and printers](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/services/printing.ts): `src/backend/services/printing.ts`

### Persistence

- [PostgreSQL access](https://github.com/anthony20602/mokhtar_forms_app/blob/main/src/backend/database/db.ts): `src/backend/database/db.ts`

### Other components

- **Office staff**
- **PostgreSQL**

## Connections

- Office staff → Office pages: uses (evidence: `README.md`)
- Office pages → People screens: opens (evidence: `src/app/(app)/page.tsx`)
- Office pages → Document editor: opens
- People screens → API client: requests (evidence: `src/frontend/components/persons/PersonSearch.tsx`)
- Document editor → API client: requests (evidence: `src/frontend/components/documents/DocumentEditor.tsx`)
- Excel import UI → API client: uploads
- Settings form → API client: requests (evidence: `src/frontend/components/settings/SettingsForm.tsx`)
- API client → API routes: fetches (evidence: `src/frontend/api/client.ts`)
- API routes → HTTP errors: wraps handlers (evidence: `src/app/api/documents/route.ts`)
- API routes → Input validation: validates input (evidence: `src/app/api/documents/route.ts`)
- API routes → Saved documents: calls (evidence: `src/app/api/documents/route.ts`)
- API routes → People registry: calls (evidence: `src/app/api/persons/route.ts`)
- API routes → Excel import: calls (evidence: `src/app/api/persons/import/preview/route.ts`)
- API routes → Office settings: calls (evidence: `src/app/api/settings/route.ts`)
- API routes → Password sessions: checks credentials (evidence: `src/app/api/auth/login/route.ts`)
- Excel import → Import rules: uses rules (evidence: `src/backend/services/personImport.ts`)
- People registry → Arabic normalization: normalizes names (evidence: `src/backend/services/persons.ts`)
- Saved documents → Arabic normalization: normalizes search (evidence: `src/backend/services/documents.ts`)
- API routes → PDF and printers: requests print or PDF (evidence: `src/app/api/documents/[id]/pdf/route.ts`)
- API routes → Saved documents: loads print document (evidence: `src/app/api/documents/[id]/pdf/route.ts`)
- Print controls → API routes: requests print
- Form catalog → Certificate letters: defines letters (evidence: `src/shared/forms/registry.ts`)
- Form catalog → Residence template: defines template (evidence: `src/shared/forms/registry.ts`)
- Document editor → Form catalog: selects form (evidence: `src/frontend/components/documents/DocumentEditor.tsx`)
- PDF and printers → Password sessions: creates print token (evidence: `src/backend/services/printing.ts`)
- People registry → PostgreSQL access: queries (evidence: `src/backend/services/persons.ts`)
- Saved documents → PostgreSQL access: queries and writes (evidence: `src/backend/services/documents.ts`)
- Excel import → PostgreSQL access: reads and imports (evidence: `src/backend/services/personImport.ts`)
- Office settings → PostgreSQL access: queries (evidence: `src/backend/services/settings.ts`)
- PostgreSQL access → PostgreSQL: connects (evidence: `src/backend/database/db.ts`)
- Office staff → Excel import UI: imports workbook (evidence: `README.md`)
- Office staff → Print controls: prints or downloads (evidence: `README.md`)
