From 9e322b70a13078e0c930c35b9892eeebd8cbfe39 Mon Sep 17 00:00:00 2001
From: stone-w4tch3r <100294019+stone-w4tch3r@users.noreply.github.com>
Date: Tue, 20 Aug 2024 20:12:51 +0500
Subject: [PATCH] Extract docs started

---
 README.md               | 408 +---------------------------------------
 docs/class-diagram.puml | 134 +++++++++++++
 docs/core-api.md        | 276 +++++++++++++++++++++++++++
 3 files changed, 413 insertions(+), 405 deletions(-)
 create mode 100644 docs/class-diagram.puml
 create mode 100644 docs/core-api.md

diff --git a/README.md b/README.md
index 6f85fdc..5df4029 100644
--- a/README.md
+++ b/README.md
@@ -234,415 +234,13 @@ class LogEntry:
 
 ### Core API
 
-```yaml
-openapi: 3.0.0
-info:
-  title: Step-CA Management API
-  version: 0.0.1
-  description: API for managing step-ca Certificate Authority
+See [docs/core-api.md](docs/core-api.md) for OpenAPI specification.
 
-servers:
-  - url: https://api.example.com/v1
-
-paths:
-  /certificates:
-    get:
-      summary: List all certificates
-      parameters:
-        - name: preview
-          in: query
-          schema:
-            type: boolean
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - type: array
-                    items:
-                      $ref: '#/components/schemas/Certificate'
-                  - $ref: '#/components/schemas/CommandPreview'
-
-  /certificates/generate:
-    post:
-      summary: Generate certificate
-      parameters:
-        - name: preview
-          in: query
-          schema:
-            type: boolean
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CertificateGenerateRequest'
-      responses:
-        '200':
-          description: Command preview or generation result
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/CertificateGenerateResult'
-                  - $ref: '#/components/schemas/CommandPreview'
-
-  /certificates/renew:
-    post:
-      summary: Preview renew certificate command
-      parameters:
-        - name: certId
-          in: query
-          required: true
-          schema:
-            type: string
-        - name: duration
-          in: query
-          required: true
-          schema:
-            type: integer
-            description: "Duration in seconds"
-        - name: preview
-          in: query
-          schema:
-            type: boolean
-      responses:
-        '200':
-          description: Command preview
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/CertificateRenewResult'
-                  - $ref: '#/components/schemas/CommandPreview'
-
-  /certificates/revoke:
-    post:
-      summary: Preview revoke certificate command
-      parameters:
-        - name: certId
-          in: query
-          required: true
-          schema:
-            type: string
-        - name: preview
-          in: query
-          schema:
-            type: boolean
-      responses:
-        '200':
-          description: Command preview
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: '#/components/schemas/CertificateRevokeResult'
-                  - $ref: '#/components/schemas/CommandPreview'
-
-  /logs/single:
-    get:
-      summary: Get log entry by ID
-      parameters:
-        - name: logId
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/LogEntry'
-
-
-  /logs:
-    get:
-      summary: Retrieve logs
-      parameters:
-        - name: severity
-          in: query
-          schema:
-            type: array
-            items:
-              type: string
-              enum: [ DEBUG, INFO, WARN, ERROR ]
-        - name: traceId
-          in: query
-          schema:
-            type: string
-            description: "UUID format"
-        - name: commandsOnly
-          in: query
-          schema:
-            type: boolean
-        - name: page
-          in: query
-          schema:
-            type: integer
-        - name: pageSize
-          in: query
-          schema:
-            type: integer
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/LogEntry'
-
-components:
-  schemas:
-    Certificate:
-      type: object
-      properties:
-        id:
-          type: string
-        name:
-          type: string
-        status:
-          type: string
-          enum: [ Active, Expired, Revoked ]
-        expirationDate:
-          type: string
-          format: date-time
-
-    CertificateGenerateRequest:
-      type: object
-      properties:
-        keyName:
-          type: string
-        keyType:
-          type: string
-          enum: [ RSA, ECDSA ]
-        duration:
-          type: string
-
-    CommandPreview:
-      type: object
-      properties:
-        command:
-          type: string
-
-    CertificateGenerateResult:
-      type: object
-      properties:
-        success:
-          type: boolean
-        message:
-          type: string
-        logEntryId:
-          type: string
-        certificateId:
-          type: string
-        certificateName:
-          type: string
-        expirationDate:
-          type: string
-          format: date-time
-
-    CertificateRenewResult:
-      type: object
-      properties:
-        success:
-          type: boolean
-        message:
-          type: string
-        logEntryId:
-          type: string
-        certificateId:
-          type: string
-        newExpirationDate:
-          type: string
-          format: date-time
-
-    CertificateRevokeResult:
-      type: object
-      properties:
-        success:
-          type: boolean
-        message:
-          type: string
-        logEntryId:
-          type: string
-        certificateId:
-          type: string
-        revocationDate:
-          type: string
-          format: date-time
-
-    LogEntry:
-      type: object
-      properties:
-        entry_id:
-          type: integer
-        timestamp:
-          type: string
-          format: date-time
-        severity:
-          type: string
-          enum: [ DEBUG, INFO, WARN, ERROR ]
-        message:
-          type: string
-        traceId:
-          type: string
-          description: "UUID format"
-        commandInfo:
-          $ref: '#/components/schemas/CommandInfo'
-          nullable: true
-          description: Contains command execution info, if entry is related to command
-
-    CommandInfo:
-      type: object
-      properties:
-        command:
-          type: string
-        output:
-          type: string
-        exitCode:
-          type: integer
-```
+---
 
 ### Class Diagram  
-```puml
-@startuml
 
-package "Shared Components" {
-  class CLIWrapper {
-    - sanitize_input(input)
-    + execute_command(command)
-  }
-
-  class Logger {
-    - log_file: str
-    + log(severity, message, trace_id, command_info)
-    + get_logs(filters)
-    + get_log_entry(log_id)
-  }
-
-  enum LogSeverity {
-    DEBUG
-    INFO
-    WARN
-    ERROR
-  }
-
-  class CommandInfo {
-    + command: str
-    + output: str
-    + exit_code: int
-    + action: str
-  }
-
-  class LogEntry {
-    + entry_id: int
-    + timestamp: datetime
-    + severity: LogSeverity
-    + message: str
-    + trace_id: UUID
-    + command_info: CommandInfo
-  }
-
-  Logger --> LogSeverity : uses
-  Logger --> LogEntry : creates
-  LogEntry --> CommandInfo : contains
-}
-
-package "WebFrontend Container" {
-  class FlaskWebServer {
-    - app: Flask
-    + run()
-    + route_dashboard()
-    + route_logs()
-    + route_certificate_management()
-  }
-
-  class UIComponents {
-    + render_dashboard()
-    + render_logs_page()
-    + render_certificate_list()
-    + render_generate_cert_modal()
-  }
-
-  class APIClient {
-    - base_url: str
-    - api_key: str
-    + get_certificates()
-    + generate_certificate(params)
-    + renew_certificate(cert_id, duration)
-    + revoke_certificate(cert_id)
-    + get_logs(filters)
-  }
-
-  FlaskWebServer --> UIComponents : uses
-  FlaskWebServer --> APIClient : uses
-}
-
-package "Core Container" {
-  class MainApplication {
-    + initialize()
-    + run()
-  }
-
-  class APIServer {
-    - app: Flask
-    + run()
-    + route_certificates()
-    + route_generate_certificate()
-    + route_renew_certificate()
-    + route_revoke_certificate()
-    + route_logs()
-  }
-
-  class CertificateManager {
-    + list_certificates()
-    + generate_certificate(params)
-    + renew_certificate(cert_id, duration)
-    + revoke_certificate(cert_id)
-  }
-
-  MainApplication --> APIServer : initializes
-  MainApplication --> CertificateManager : uses
-  MainApplication --> Logger : uses
-
-  APIServer --> CertificateManager : uses
-  APIServer --> Logger : uses
-
-  CertificateManager --> CLIWrapper : uses
-  CertificateManager --> Logger : uses
-}
-
-package "AutoSetup Component" {
-  class AutoSetup {
-    + install_stepca()
-    + setup_stepca()
-    + create_root_certificate()
-    + prepare_mtls_certificates()
-    + run_docker_compose()
-  }
-
-  AutoSetup --> CLIWrapper : uses
-  AutoSetup --> Logger : uses
-}
-
-
-package "Host System" {
-    rectangle "step-ca CLI" as stepca {
-    }
-}
-
-CLIWrapper --> stepca : executes commands
-
-APIClient ..> APIServer : communicates via mTLS
-
-@enduml
-```
+See XXX
 
 ### File structure
 ```
diff --git a/docs/class-diagram.puml b/docs/class-diagram.puml
new file mode 100644
index 0000000..02c49ff
--- /dev/null
+++ b/docs/class-diagram.puml
@@ -0,0 +1,134 @@
+This diagram describes the class structure of the application's python components.
+
+@startuml
+
+package "Shared Components" {
+  class CLIWrapper {
+    - sanitize_input(input)
+    + execute_command(command)
+  }
+
+  class Logger {
+    - log_file: str
+    + log(severity, message, trace_id, command_info)
+    + get_logs(filters)
+    + get_log_entry(log_id)
+  }
+
+  enum LogSeverity {
+    DEBUG
+    INFO
+    WARN
+    ERROR
+  }
+
+  class CommandInfo {
+    + command: str
+    + output: str
+    + exit_code: int
+    + action: str
+  }
+
+  class LogEntry {
+    + entry_id: int
+    + timestamp: datetime
+    + severity: LogSeverity
+    + message: str
+    + trace_id: UUID
+    + command_info: CommandInfo
+  }
+
+  Logger --> LogSeverity : uses
+  Logger --> LogEntry : creates
+  LogEntry --> CommandInfo : contains
+}
+
+package "WebFrontend Container" {
+  class FlaskWebServer {
+    - app: Flask
+    + run()
+    + route_dashboard()
+    + route_logs()
+    + route_certificate_management()
+  }
+
+  class UIComponents {
+    + render_dashboard()
+    + render_logs_page()
+    + render_certificate_list()
+    + render_generate_cert_modal()
+  }
+
+  class APIClient {
+    - base_url: str
+    - api_key: str
+    + get_certificates()
+    + generate_certificate(params)
+    + renew_certificate(cert_id, duration)
+    + revoke_certificate(cert_id)
+    + get_logs(filters)
+  }
+
+  FlaskWebServer --> UIComponents : uses
+  FlaskWebServer --> APIClient : uses
+}
+
+package "Core Container" {
+  class MainApplication {
+    + initialize()
+    + run()
+  }
+
+  class APIServer {
+    - app: Flask
+    + run()
+    + route_certificates()
+    + route_generate_certificate()
+    + route_renew_certificate()
+    + route_revoke_certificate()
+    + route_logs()
+  }
+
+  class CertificateManager {
+    + list_certificates()
+    + generate_certificate(params)
+    + renew_certificate(cert_id, duration)
+    + revoke_certificate(cert_id)
+  }
+
+  MainApplication --> APIServer : initializes
+  MainApplication --> CertificateManager : uses
+  MainApplication --> Logger : uses
+
+  APIServer --> CertificateManager : uses
+  APIServer --> Logger : uses
+
+  CertificateManager --> CLIWrapper : uses
+  CertificateManager --> Logger : uses
+}
+
+package "AutoSetup Component" {
+  class AutoSetup {
+    + install_stepca()
+    + setup_stepca()
+    + create_root_certificate()
+    + prepare_mtls_certificates()
+    + run_docker_compose()
+  }
+
+  AutoSetup --> CLIWrapper : uses
+  AutoSetup --> Logger : uses
+}
+
+
+package "Host System" {
+    rectangle "step-ca CLI" as stepca {
+    }
+}
+
+CLIWrapper --> stepca : executes commands
+
+APIClient ..> APIServer : communicates via mTLS
+
+@enduml
+```
diff --git a/docs/core-api.md b/docs/core-api.md
new file mode 100644
index 0000000..254d9fb
--- /dev/null
+++ b/docs/core-api.md
@@ -0,0 +1,276 @@
+# API specification for Core API
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Step-CA Management API
+  version: 0.0.1
+  description: API for managing step-ca Certificate Authority
+
+servers:
+  - url: https://api.example.com/v1
+
+paths:
+  /certificates:
+    get:
+      summary: List all certificates
+      parameters:
+        - name: preview
+          in: query
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/Certificate'
+                  - $ref: '#/components/schemas/CommandPreview'
+
+  /certificates/generate:
+    post:
+      summary: Generate certificate
+      parameters:
+        - name: preview
+          in: query
+          schema:
+            type: boolean
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CertificateGenerateRequest'
+      responses:
+        '200':
+          description: Command preview or generation result
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/CertificateGenerateResult'
+                  - $ref: '#/components/schemas/CommandPreview'
+
+  /certificates/renew:
+    post:
+      summary: Preview renew certificate command
+      parameters:
+        - name: certId
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: duration
+          in: query
+          required: true
+          schema:
+            type: integer
+            description: "Duration in seconds"
+        - name: preview
+          in: query
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Command preview
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/CertificateRenewResult'
+                  - $ref: '#/components/schemas/CommandPreview'
+
+  /certificates/revoke:
+    post:
+      summary: Preview revoke certificate command
+      parameters:
+        - name: certId
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: preview
+          in: query
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Command preview
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/CertificateRevokeResult'
+                  - $ref: '#/components/schemas/CommandPreview'
+
+  /logs/single:
+    get:
+      summary: Get log entry by ID
+      parameters:
+        - name: logId
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LogEntry'
+
+
+  /logs:
+    get:
+      summary: Retrieve logs
+      parameters:
+        - name: severity
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [ DEBUG, INFO, WARN, ERROR ]
+        - name: traceId
+          in: query
+          schema:
+            type: string
+            description: "UUID format"
+        - name: commandsOnly
+          in: query
+          schema:
+            type: boolean
+        - name: page
+          in: query
+          schema:
+            type: integer
+        - name: pageSize
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LogEntry'
+
+components:
+  schemas:
+    Certificate:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          enum: [ Active, Expired, Revoked ]
+        expirationDate:
+          type: string
+          format: date-time
+
+    CertificateGenerateRequest:
+      type: object
+      properties:
+        keyName:
+          type: string
+        keyType:
+          type: string
+          enum: [ RSA, ECDSA ]
+        duration:
+          type: string
+
+    CommandPreview:
+      type: object
+      properties:
+        command:
+          type: string
+
+    CertificateGenerateResult:
+      type: object
+      properties:
+        success:
+          type: boolean
+        message:
+          type: string
+        logEntryId:
+          type: string
+        certificateId:
+          type: string
+        certificateName:
+          type: string
+        expirationDate:
+          type: string
+          format: date-time
+
+    CertificateRenewResult:
+      type: object
+      properties:
+        success:
+          type: boolean
+        message:
+          type: string
+        logEntryId:
+          type: string
+        certificateId:
+          type: string
+        newExpirationDate:
+          type: string
+          format: date-time
+
+    CertificateRevokeResult:
+      type: object
+      properties:
+        success:
+          type: boolean
+        message:
+          type: string
+        logEntryId:
+          type: string
+        certificateId:
+          type: string
+        revocationDate:
+          type: string
+          format: date-time
+
+    LogEntry:
+      type: object
+      properties:
+        entry_id:
+          type: integer
+        timestamp:
+          type: string
+          format: date-time
+        severity:
+          type: string
+          enum: [ DEBUG, INFO, WARN, ERROR ]
+        message:
+          type: string
+        traceId:
+          type: string
+          description: "UUID format"
+        commandInfo:
+          $ref: '#/components/schemas/CommandInfo'
+          nullable: true
+          description: Contains command execution info, if entry is related to command
+
+    CommandInfo:
+      type: object
+      properties:
+        command:
+          type: string
+        output:
+          type: string
+        exitCode:
+          type: integer
+```