Rollingcat-Software · ahmetabdullahgultekin · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/01-getting-started/INTEGRATION_GUIDE.md b/01-getting-started/INTEGRATION_GUIDE.md
@@ -33,8 +33,8 @@ Add FIVUCSAS biometric auth to any page with a single script tag.
 <body>
   <button id="login-btn">Log In with FIVUCSAS</button>
 
-  <!-- 1. Load the SDK -->
-  <script src="https://verify.fivucsas.com/sdk/fivucsas-auth.iife.js"></script>
+  <!-- 1. Load the SDK (CDN — live at https://verify.fivucsas.com/) -->
+  <script src="https://verify.fivucsas.com/fivucsas-auth.js"></script>
 
   <script>
     // 2. Initialize with your client ID
@@ -260,19 +260,22 @@ The auth widget (`verify.fivucsas.com`) runs in a sandboxed iframe and handles c
 
 ### Option A — `@fivucsas/auth-js` (Vanilla JS)
 
-**CDN (IIFE, zero dependencies):**
+> **Delivery status:** The CDN is live at `https://verify.fivucsas.com/`. npm packages (`@fivucsas/auth-*`) are **not yet published** — use the CDN paths below until npm availability is announced.
+
+**CDN — IIFE (zero dependencies, browser globals):**
 ```html
-<script src="https://verify.fivucsas.com/sdk/fivucsas-auth.iife.js"></script>
+<script src="https://verify.fivucsas.com/fivucsas-auth.js"></script>
 ```
 
-**ESM import:**
+**CDN — ESM (for `<script type="module">` or import maps):**
 ```js
-import { FivucsasAuth } from 'https://verify.fivucsas.com/sdk/fivucsas-auth.esm.js';
+import { FivucsasAuth } from 'https://verify.fivucsas.com/fivucsas-auth.esm.js';
 ```
 
-**npm (if bundling):**
+**npm (coming soon — not yet published):**
 ```bash
-npm install @fivucsas/auth-js
+# Not available yet — use the CDN URLs above
+# npm install @fivucsas/auth-js
 ```
 
 **Usage:**
@@ -338,8 +341,11 @@ auth.destroy();
 
 ### Option B — `@fivucsas/auth-react`
 
+> **Not yet published on npm.** Load auth-js via CDN and use the raw postMessage API or Option D (raw iframe) in the meantime. This section documents the planned React API.
+
 ```bash
-npm install @fivucsas/auth-react
+# Coming soon — not yet published
+# npm install @fivucsas/auth-react
 ```
 
 **Wrap your app with `<FivucsasProvider>`:**
@@ -426,12 +432,15 @@ function CustomLogin() {
 | `error` | `Error \| null` | Last error |
 | `reset` | `() => void` | Clear result and error state |
 
-### Option C — `@fivucsas/auth-elements` (Web Components — coming soon)
+### Option C — `@fivucsas/auth-elements` (Web Components — coming soon, not yet published)
+
+> **Not yet published.** The CDN file `fivucsas-auth-elements.js` is not yet live. Use Option A or Option D until this is released.
 
-Declarative HTML, framework-agnostic:
+Planned declarative HTML, framework-agnostic usage:
 
 ```html
-<script src="https://verify.fivucsas.com/sdk/fivucsas-auth-elements.js"></script>
+<script src="https://verify.fivucsas.com/fivucsas-auth-elements.js"></script>
+<!-- NOTE: file not yet published — check https://verify.fivucsas.com for availability -->
 
 <fivucsas-verify
   client-id="fiv_YOUR_CLIENT_ID"
@@ -793,19 +802,19 @@ Content-Security-Policy:
 - [ ] Tested on mobile (camera permission prompt, touch fingerprint)
 - [ ] Tested Escape / backdrop click cancellation (should not cause errors)
 - [ ] Tested token expiration and refresh
-- [ ] Verified Swagger docs at https://api.fivucsas.com/swagger-ui.html for latest endpoint signatures
+- [ ] Verified Swagger docs at `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated, 403 from external IPs) for latest endpoint signatures
 
 ---
 
 ## Quick Reference
 
 | Resource | URL |
 |----------|-----|
-| Identity API | https://api.fivucsas.com |
+| Identity API | `https://api.fivucsas.com` (auth required — returns 401 without a valid Bearer token) |
 | Auth Widget | https://verify.fivucsas.com |
 | Developer Portal | https://app.fivucsas.com/developer-portal |
 | Widget Demo | https://app.fivucsas.com/widget-demo |
-| Swagger UI | https://api.fivucsas.com/swagger-ui.html |
+| Swagger UI | `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated — returns 403 from external IPs) |
 | OIDC Discovery | https://api.fivucsas.com/.well-known/openid-configuration |
 | JWKS | https://api.fivucsas.com/.well-known/jwks.json |
 | Auth Flow Builder | https://app.fivucsas.com/auth-flow-builder |
@@ -815,6 +824,6 @@ Content-Security-Policy:
 
 ## Support
 
-- **Swagger UI**: Full endpoint documentation at https://api.fivucsas.com/swagger-ui.html
+- **Swagger UI**: Full endpoint documentation at `https://api.fivucsas.com/swagger-ui.html` (admin-IP-gated — returns 403 from external IPs)
 - **Widget Demo**: Live integration demo at https://app.fivucsas.com/widget-demo
 - **Developer Portal**: Manage your apps at https://app.fivucsas.com/developer-portal
diff --git a/01-getting-started/tenant-onboarding.md b/01-getting-started/tenant-onboarding.md
@@ -14,13 +14,21 @@ A button on your site that, when clicked, takes the user to `verify.fivucsas.com
 
 ## 5-minute quickstart
 
-### 1. Install the SDK
+### 1. Load the SDK
 
-```bash
-npm install @fivucsas/auth-js
+> **npm packages (`@fivucsas/auth-*`) are not yet published.** Use the CDN instead:
+
+```html
+<!-- IIFE build — browser globals, zero bundler required -->
+<script src="https://verify.fivucsas.com/fivucsas-auth.js"></script>
+```
+
+```js
+// ESM build — for <script type="module"> or import maps
+import { FivucsasAuth } from 'https://verify.fivucsas.com/fivucsas-auth.esm.js';
 ```
 
-For React projects, `@fivucsas/auth-react` is also available with hooks and ready-made components — see the integration guide. The rest of this quickstart assumes vanilla JS.
+For React projects, `@fivucsas/auth-react` is planned with hooks and ready-made components (not yet published — see the integration guide). The rest of this quickstart uses the vanilla JS SDK.
 
 ### 2. Initiate the login
 
@@ -110,9 +118,9 @@ Each registered URI is enforced character-for-character; trailing slashes matter
 - `client_id` is **not a secret** — it is safe to bundle into your SPA build.
 - `client_secret`, if you have one, is a real secret. Never check it into git, never ship it to the browser. Use it only from server-side code with an environment variable.
 
-### d. Install the SDK and wire `loginRedirect`
+### d. Load the SDK and wire `loginRedirect`
 
-See the 5-minute quickstart above.
+See the 5-minute quickstart above (CDN delivery — npm not yet published).
 
 ### e. Handle the code exchange
 

diff --git a/02-architecture/ARCHITECTURE_DIAGRAMS.md b/02-architecture/ARCHITECTURE_DIAGRAMS.md
@@ -486,7 +486,7 @@ sequenceDiagram
     alt User Found
         ICA->>ICA: Verify BCrypt Password
         alt Password Valid
-            ICA->>ICA: Generate JWT (HS512)
+            ICA->>ICA: Generate JWT (RS256)
             ICA->>ICA: Generate Refresh Token
             ICA->>RD: Store Session
             ICA->>DB: Log Login Event
@@ -938,8 +938,40 @@ graph TB
 
 ---
 
+## 11. Draw.io Source Diagrams
+
+The `diagrams/` folder contains editable draw.io XML sources. Open any `.drawio` file at [app.diagrams.net](https://app.diagrams.net) to view or edit.
+
+| File | Topic | Status |
+|------|-------|--------|
+| [`system_architecture.drawio`](../diagrams/system_architecture.drawio) | Full system layered view (clients → gateway → services → data) | Accurate — JWT RS256 corrected 2026-05-28 |
+| [`hexagonal_architecture.drawio`](../diagrams/hexagonal_architecture.drawio) | Ports & Adapters / DDD for Identity Core API | Accurate |
+| [`er_diagram.drawio`](../diagrams/er_diagram.drawio) | Database ER diagram — core tables | Broadly accurate (pre-V55 schema; see Flyway migrations for V55–V60 column changes) |
+| [`use_case_diagram.drawio`](../diagrams/use_case_diagram.drawio) | Use cases by actor (End User, Tenant Admin, System Admin, External) | Accurate |
+| [`biometric_puzzle_flow.drawio`](../diagrams/biometric_puzzle_flow.drawio) | Active liveness challenge flow (blink / smile / turn) | Accurate |
+| [`data_flow_diagram.drawio`](../diagrams/data_flow_diagram.drawio) | DFD Level 1 — face verification and identity management | Accurate |
+| [`nfc_handshake.drawio`](../diagrams/nfc_handshake.drawio) | NFC BAC authentication handshake (ICAO 9303 / ISO 14443) | Accurate |
+| [`deployment_architecture.drawio`](../diagrams/deployment_architecture.drawio) | Docker Compose topology | **Needs regeneration** — shows NGINX as gateway; production uses Traefik (see infra/traefik/) |
+| [`ml_pipeline.drawio`](../diagrams/ml_pipeline.drawio) | Face recognition pipeline (input → detect → align → extract → match) | Accurate — 9 DeepFace models shown (VGG-Face, FaceNet, ArcFace, etc.); MobileFaceNet was a separate stripped model not listed here |
+| [`technology_stack.drawio`](../diagrams/technology_stack.drawio) | Full technology stack per layer | **Partially stale** — API gateway section shows NGINX; prod uses Traefik. JWT RS256 is correctly shown. |
+| [`implementation_progress.drawio`](../diagrams/implementation_progress.drawio) | Progress bars — Fall 2025 snapshot | **Stale** — percentages reflect Fall 2025; project is now 98%+ complete (V60 migrations applied). |
+
+## 12. Additional PNG Diagrams
+
+The `ADD_diagrams/` folder contains exported PNG diagrams produced alongside the early development phase.
+
+| File | Topic | Status |
+|------|-------|--------|
+| [`diagram_01_use_cases_by_actor.png`](../ADD_diagrams/diagram_01_use_cases_by_actor.png) | Use cases grouped by actor (wide layout) | Accurate — complements §10 above |
+| [`diagram_02_domain_model___core_entities.png`](../ADD_diagrams/diagram_02_domain_model___core_entities.png) | UML class diagram — Tenant / User / BiometricData / Role / AuditLog / VerificationLog | Accurate |
+| [`diagram_03_entity_relationship_diagram.png`](../ADD_diagrams/diagram_03_entity_relationship_diagram.png) | Full ER schema export | Broadly accurate; see Flyway V55–V60 for latest column changes (refresh_tokens.token column dropped V60) |
+| [`diagram_04_system_architecture_overview.png`](../ADD_diagrams/diagram_04_system_architecture_overview.png) | Layered architecture block diagram | **Needs regeneration** — shows NGINX gateway and "DeepFace 9 Models"; prod uses Traefik and MobileFaceNet was removed |
+| [`diagram_05_docker_deployment.png`](../ADD_diagrams/diagram_05_docker_deployment.png) | Docker network topology | **Needs regeneration** — shows nginx:8000 and web-app:5173; prod uses Traefik and the widget app is verify.fivucsas.com |
+
+---
+
 **Document Location:** `docs/02-architecture/ARCHITECTURE_DIAGRAMS.md`
 **Related Documents:**
 - [Architecture Analysis](ARCHITECTURE_ANALYSIS.md)
-- [System Design Decisions](SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md)
+- System Design Decisions
 - [PlantUML Diagrams](diagrams/PLANTUML_DIAGRAMS.md)
diff --git a/02-architecture/EMBEDDABLE_AUTH_WIDGET_ARCHITECTURE.md b/02-architecture/EMBEDDABLE_AUTH_WIDGET_ARCHITECTURE.md
@@ -48,48 +48,31 @@ Layer 3: Secure Capture (iframe from verify.fivucsas.com)
 
 ### Integration Code (What Developers Write)
 
-**Option A: Script Tag (simplest, like reCAPTCHA)**
+**Option A: Script Tag (simplest, like reCAPTCHA) — CDN live**
+
+> The IIFE and ESM builds are available at `https://verify.fivucsas.com/`. npm packages are **not yet published**.
+
 ```html
-<script src="https://cdn.fivucsas.com/auth-elements@1/fivucsas.min.js"></script>
-
-<fivucsas-verify
-  client-id="fiv_live_abc123"
-  flow="login"
-  theme="auto"
-  lang="tr"
-  on-complete="handleVerified">
-</fivucsas-verify>
-
-<script>
-function handleVerified(event) {
-  const { authCode, userId } = event.detail;
-  fetch('/api/auth/fivucsas-callback', {
-    method: 'POST',
-    body: JSON.stringify({ code: authCode })
-  });
-}
-</script>
+<!-- IIFE build (live) -->
+<script src="https://verify.fivucsas.com/fivucsas-auth.js"></script>
+
+<!-- Web Components build (coming soon — not yet live):
+<script src="https://verify.fivucsas.com/fivucsas-auth-elements.js"></script>
+-->
 ```
 
-**Option B: React**
+**Option B: React — coming soon (npm not yet published)**
 ```tsx
-import { FivucsasProvider, VerifyButton } from '@fivucsas/auth-react';
-
-function App() {
-  return (
-    <FivucsasProvider clientId="fiv_live_abc123">
-      <VerifyButton
-        flow="login"
-        onComplete={({ authCode }) => { /* exchange code */ }}
-      />
-    </FivucsasProvider>
-  );
-}
+// @fivucsas/auth-react is not yet on npm.
+// In the meantime, use the CDN IIFE build (Option C) wrapped in a useEffect.
+// import { FivucsasProvider, VerifyButton } from '@fivucsas/auth-react'; // future
 ```
 
-**Option C: Programmatic**
+**Option C: Programmatic (CDN ESM)**
 ```typescript
-import { FivucsasAuth } from '@fivucsas/auth-js';
+import { FivucsasAuth } from 'https://verify.fivucsas.com/fivucsas-auth.esm.js';
+// or via IIFE: window.FivucsasAuth after loading fivucsas-auth.js
+// @fivucsas/auth-js npm package is not yet published
 
 const auth = new FivucsasAuth({ clientId: 'fiv_live_abc123' });
 const result = await auth.verify({

diff --git a/02-architecture/README.md b/02-architecture/README.md
@@ -12,12 +12,12 @@ System architecture, design decisions, and architectural diagrams.
 - **[MODULE_STRUCTURE.md](MODULE_STRUCTURE.md)** - ⭐ Official module structure and organization (NEW)
 - **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** - ⭐ Mermaid diagrams for SE (NEW)
 - **[ARCHITECTURE_ANALYSIS.md](ARCHITECTURE_ANALYSIS.md)** - Comprehensive architecture analysis
-- **[SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md](SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md)** - Design decisions
+- **SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md** - Design decisions
 
 ### Audits & Reports
-- **[PROJECT_DESIGN_AUDIT.md](PROJECT_DESIGN_AUDIT.md)** - Design audit report
-- **[DESIGN_AUDIT_REPORT.md](DESIGN_AUDIT_REPORT.md)** - Detailed audit findings
-- **[PROJECT_DESIGN_AND_STATUS_ANALYSIS.md](PROJECT_DESIGN_AND_STATUS_ANALYSIS.md)** - Design and status analysis
+- **PROJECT_DESIGN_AUDIT.md** - Design audit report
+- **DESIGN_AUDIT_REPORT.md** - Detailed audit findings
+- **PROJECT_DESIGN_AND_STATUS_ANALYSIS.md** - Design and status analysis
 
 ---
 
@@ -36,6 +36,19 @@ See **[ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md)** for:
 - Entity Relationship Diagram
 - Use Case Diagram
 
+### Draw.io Source Diagrams
+See [diagrams/](../diagrams/) folder for editable `.drawio` XML sources:
+- `system_architecture.drawio` — layered system view (JWT RS256, accurate as of 2026-05-28)
+- `hexagonal_architecture.drawio` — Ports & Adapters / DDD for Identity Core API
+- `er_diagram.drawio` — core database ER schema
+- `use_case_diagram.drawio` — actors and use cases
+- `biometric_puzzle_flow.drawio` — active liveness challenge protocol
+- `data_flow_diagram.drawio` — DFD Level 1
+- `nfc_handshake.drawio` — BAC handshake (ICAO 9303)
+
+Diagrams needing regeneration: `deployment_architecture.drawio`, `technology_stack.drawio` (NGINX→Traefik), `implementation_progress.drawio` (stale Fall-2025 percentages).
+See §11–12 of [ARCHITECTURE_DIAGRAMS.md](ARCHITECTURE_DIAGRAMS.md) for full per-diagram status.
+
 ### PlantUML Diagrams
 See [diagrams/](diagrams/) folder for 35+ professional UML diagrams:
 - Entity-Relationship (ER) diagrams
@@ -46,6 +59,11 @@ See [diagrams/](diagrams/) folder for 35+ professional UML diagrams:
 - Network architecture diagrams
 - Security architecture diagrams
 
+### Additional PNG Diagrams
+See [ADD_diagrams/](../ADD_diagrams/) for exported PNGs from the early development phase.
+Accurate: `diagram_01_use_cases_by_actor.png`, `diagram_02_domain_model___core_entities.png`, `diagram_03_entity_relationship_diagram.png`.
+Needs regeneration: `diagram_04_system_architecture_overview.png`, `diagram_05_docker_deployment.png` (NGINX→Traefik, MobileFaceNet removed).
+
 ---
 
 ## Module Overview

diff --git a/02-architecture/security.md b/02-architecture/security.md
@@ -605,8 +605,8 @@ Required elements:
 ### Security Contacts
 
 ```
-Security Team: security@fivucsas.com
-Vulnerability Disclosure: security@fivucsas.com (PGP key available)
+Security Team: info@fivucsas.com
+Vulnerability Disclosure: info@fivucsas.com (primary) | rollingcat.help@gmail.com (alternate)
 Incident Hotline: +1-555-SECURITY (24/7)
 ```
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -4,7 +4,7 @@
 
 If you believe you've found a security vulnerability in docs — the documentation repository of the FIVUCSAS biometric authentication platform — please report it privately so we can fix it before disclosing publicly.
 
-**Email:** info@app.fivucsas.com (subject prefix: `[SECURITY] docs`)
+**Email:** info@fivucsas.com (subject prefix: `[SECURITY] docs`) — alternate: rollingcat.help@gmail.com
 
 Please include:
 - A clear description of the issue and its impact.

diff --git a/diagrams/system_architecture.drawio b/diagrams/system_architecture.drawio
@@ -79,7 +79,7 @@
         </mxCell>
 
         <!-- Identity Core Features -->
-        <mxCell id="id-feat1" value="JWT Authentication&#xa;(HS512 + Refresh)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#c6f6d5;strokeColor=#48bb78;fontSize=10;" vertex="1" parent="1">
+        <mxCell id="id-feat1" value="JWT Authentication&#xa;(RS256 + Refresh)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#c6f6d5;strokeColor=#48bb78;fontSize=10;" vertex="1" parent="1">
           <mxGeometry x="135" y="395" width="110" height="40" as="geometry" />
         </mxCell>
         <mxCell id="id-feat2" value="Multi-Tenancy&#xa;(Row-Level Security)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#c6f6d5;strokeColor=#48bb78;fontSize=10;" vertex="1" parent="1">