If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kekingcn/kkFileView shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 1w ago
• 5 active contributors
• CI configured
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kekingcn/kkFileView repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kekingcn/kkFileView.

What it runs against: a local clone of kekingcn/kkFileView — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kekingcn/kkFileView | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kekingcn/kkFileView. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kekingcn/kkFileView.git
#   cd kkFileView
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kekingcn/kkFileView and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kekingcn/kkFileView(\\.git)?\\b" \\
  && ok "origin remote is kekingcn/kkFileView" \\
  || miss "origin remote is not kekingcn/kkFileView (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f ".github/workflows/maven.yml" \\
  && ok ".github/workflows/maven.yml" \\
  || miss "missing critical file: .github/workflows/maven.yml"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "docker/kkfileview-base/Dockerfile" \\
  && ok "docker/kkfileview-base/Dockerfile" \\
  || miss "missing critical file: docker/kkfileview-base/Dockerfile"
test -f "SECURITY_CONFIG.md" \\
  && ok "SECURITY_CONFIG.md" \\
  || miss "missing critical file: SECURITY_CONFIG.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kekingcn/kkFileView"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

kkFileView is a Spring Boot-based universal file online preview server that converts 100+ document formats (Office docs, PDFs, CAD files, 3D models, images, videos, archives) into browser-viewable formats. It provides REST API endpoints to preview files without client-side plugins by internally orchestrating LibreOffice/OpenOffice conversions, image processing, and specialized renderers. Multi-module Maven monorepo (kkFileView-parent) with modular format handlers. Architecture separates format detection → conversion orchestration → rendering pipeline. Each document type (Office, PDF, CAD, 3D, image, video, archive) has dedicated converter/preview implementations that inherit from abstract preview interface. REST controller layer exposes /preview endpoints. Docker base image (docker/kkfileview-base/Dockerfile) bundles LibreOffice and system libraries.

Backend developers and DevOps engineers building SaaS platforms, document management systems, or enterprise portals who need to embed document preview functionality server-side without distributing conversion logic to clients. Teams managing heterogeneous document ecosystems (mixed Office, CAD, PDF, media formats) need a single deployment.

Actively maintained (v5.0.0, Java 21 target, Spring Boot 3.5.6). GitHub workflows show automated testing (maven.yml, nightly-e2e.yml, pr-e2e-mvp.yml), Docker deployment pipelines, and issue templates. Production-ready with documented security config (SECURITY_CONFIG.md) and multi-platform support (Windows/Linux deployment scripts in .github/scripts/).

Heavy dependency on external conversion engines (LibreOffice, Aspose CAD, FFmpeg, OpenCV via JavaCV) means system stability depends on those services. Large JVM heap requirements for processing big files (multiple image/video codecs loaded). Single-maintainer risk likely (kekingcn organization). Watch for Java 21 adoption curve and Spring Boot 3.x migration complexity in consumer projects.

GitHub Actions workflows (master-auto-deploy.yml) deploy on commits to master. Recent focus on E2E testing (nightly-e2e.yml, e2e-improvement-checklist.md). Windows deployment automation via PowerShell (remote_windows_deploy.ps1). Copilot issue auto-commenting suggests active community triage. Security configuration docs added (SECURITY_CONFIG.md).

git clone https://github.com/kekingcn/kkFileView.git
cd kkFileView
mvn clean install -DskipTests
mvn spring-boot:run -pl kkfileview-server

Server starts on http://localhost:8080. For Docker: docker build -f Dockerfile -t kkfileview . && docker run -p 8080:8080 kkfileview.

Daily commands: Development:

mvn clean install
mvn -pl kkfileview-server spring-boot:run

Server listens on port 8080. Docker:

docker build -f Dockerfile -t kkfileview:latest .
docker run -p 8080:8080 -e JAVA_OPTS="-Xmx2g" kkfileview:latest

Check health: curl http://localhost:8080/index.html.

• pom.xml — Root Maven POM defining the parent project structure, Java 21 target, and all dependency versions for the entire kkFileView ecosystem.
• .github/workflows/maven.yml — CI/CD pipeline configuration that builds, tests, and packages the Spring Boot application on every commit.
• Dockerfile — Container image definition that packages the application and all required dependencies (LibreOffice, fonts) for deployment.
• docker/kkfileview-base/Dockerfile — Base Docker image layer providing LibreOffice and system dependencies required for document conversion operations.
• SECURITY_CONFIG.md — Documents security configuration and best practices for file upload handling and preview generation in this multi-format preview system.
• README.md — Primary documentation covering supported file formats, setup instructions, and feature overview for all contributors.
• .github/workflows/master-auto-deploy.yml — Automated deployment pipeline orchestrating Windows and Linux deployments via WinRM and remote scripts.

Add support for a new document format (e.g., new Office variant)

1. Verify LibreOffice can convert the format and test locally with a sample file (docker/kkfileview-base/Dockerfile)
2. Add the new file extension to the supported formats list in project configuration (pom.xml)
3. Create a new converter/handler class in the Spring Boot application (typically in server/src/main/java/cn/keking/service/impl/) (README.md)
4. Register the converter in the Spring configuration or factory bean (pom.xml)
5. Add test cases for the new format in E2E tests (.github/workflows/nightly-e2e.yml)
6. Update README.md with the new supported format and any special requirements (README.md)

Deploy a new version to production

1. Verify all tests pass by checking the Maven workflow (.github/workflows/maven.yml)
2. Update version in pom.xml (e.g., 5.0.0 → 5.1.0) (pom.xml)
3. Merge to master branch to trigger automated deployment (.github/workflows/master-auto-deploy.yml)
4. Verify Windows deployment via WinRM script execution (.github/scripts/deploy_windows_winrm.py)
5. Confirm Docker image build and container registry push (Dockerfile)

Enhance security and file upload handling

1. Review current security configuration and constraints (SECURITY_CONFIG.md)
2. Update file type whitelist and size limits in Spring Boot application configuration (pom.xml)
3. Add validation logic in the file upload handler (typically in server/src/main/java/cn/keking/controller/) (README.md)
4. Add security-focused E2E tests to verify upload restrictions (.github/workflows/nightly-e2e.yml)
5. Document security changes and best practices in SECURITY_CONFIG.md (SECURITY_CONFIG.md)

• Spring Boot — Provides rapid development framework for REST APIs, embedded web server, and simplified Java configuration for document processing service
• LibreOffice / LibreOffice Portable — Cross-platform document conversion engine supporting 100+ formats (Office, ODF, WPS, PDF, etc.) via headless UNO interface
• Docker & Docker Compose — Containerizes application with all dependencies (LibreOffice, fonts, system libs) for consistent deployment across Linux/Windows/cloud
• Maven — Dependency management and build automation with multi-module support (parent pom) for consistent version control
• GitHub Actions — Native CI/CD automation for Maven builds, Docker image publishing, and cross-platform (Windows/Linux) deployment via WinRM

• Embedded LibreOffice Portable vs. external microservice

  • Why: Simplifies deployment and reduces infrastructure complexity; allows single-server deployments without external dependencies
  • Consequence: Limits scalability—each server instance includes full LibreOffice runtime (large disk/memory footprint); conversion performance tied to single machine resources

• Java 21 (latest LTS) as minimum version

  • Why: Leverages modern JVM features (virtual threads, records, pattern matching) for better performance and maintainability
  • Consequence: Requires organizations to upgrade to Java 21+; legacy Java 8/11 deployments must migrate

• File preview caching in memory/local storage

  • Why: Reduces conversion overhead for repeated preview requests; simple implementation without external cache stores (Redis)
  • Consequence: Cache not shared across instances in distributed setups; requires cache busting logic on file updates

• Support 50+ file formats in single application

  • Why: Provides comprehensive document preview solution; reduces need for multiple specialized services
  • Consequence: Increased complexity, larger deployment size, slower startup; greater surface area for format-specific bugs

• Does not provide real-time collaborative editing—only preview/conversion of static documents
• Does not implement user authentication or multi-tenancy—operates as a standalone conversion service
• Does not handle video transcoding—audio/video support limited to browser-native playback
• Does not support blockchain or distributed storage backends—local/mounted filesystem only
• Not a document database or content management system—no full-text indexing or search capabilities
• Does not provide font subsetting or advanced typography control—uses system/bundled fonts
• Not optimized for real-time streaming of very large files (>1GB)—designed for office document preview (<100MB typical)

LibreOffice/OpenOffice must be installed on the host or Docker container for Office document conversion (JODConverter is a wrapper, not a re-implementation). Large heap allocation required: Java heap defaults insufficient for multi-page document conversions; set -Xmx2g minimum. System fonts matter: Missing font files cause rendering issues in converted PDFs; docker/kkfileview-base/fonts/ directory is critical. FFmpeg/OpenCV codecs: Video/3D preview depends on system-installed FFmpeg and libopenblaslib; CPU architectures must match bytedeco prebuilt binaries or native compilation fails silently. Aspose CAD is proprietary: License key may be required for production CAD previews (check pom.xml aspose-cad-java version and Aspose terms). Temp file cleanup: Large file uploads generate temp artifacts; ensure /tmp or system temp dir has sufficient space and cleanup scheduled.

• Format Conversion via LibreOffice Headless — kkFileView's core strategy for heterogeneous document formats: delegates to LibreOffice in headless mode rather than re-implementing parsers. Knowing how JODConverter orchestrates this (UNO sockets, process pools, format rules) is essential for debugging conversion failures.
• Strategy Pattern for Preview Adapters — Each format (PDF, Office, CAD, 3D, image, video) has a dedicated *PreviewImpl class implementing the FilePreview interface. Understanding this pattern lets you add new formats by writing one new adapter without touching core logic.
• Spring Boot Dependency Injection for Document Handlers — Format converters are likely autowired via Spring @Component or @Bean. When debugging why a format isn't being recognized, trace the component scan and bean registration in Spring context.
• [Multi-layered Image Processing (JAI, ImageIO, Commons Imaging)](https://jai.dev.java.net/ and https://commons.apache.org/proper/commons-imaging/) — kkFileView uses three image libraries in sequence (JAI for codec extension, ImageIO for standard formats, Commons Imaging as fallback). Understanding the fallback chain prevents mysterious image preview failures.
• FFmpeg Codec Abstraction via JavaCV — Video and 3D model rendering depend on JavaCV's native bindings to FFmpeg. JAR excludes or architecture mismatches cause silent codec failures; know how to validate your system's FFmpeg via bytedeco CLI.
• Temp File Management in High-Volume Document Processing — Document conversion creates intermediate files (PDF cache, image extracts, 7z temp archives). In production, disk space and file descriptor limits are real bottlenecks; understand temp cleanup policies to prevent /tmp exhaustion.
• REST Streaming for Large Preview Output — Multi-page PDF or large image previews must stream rather than buffer in heap. Spring's StreamingResponseBody or chunked transfer encoding is likely used; know how to verify memory efficiency in your deployment.

• OpenOffice/core — Upstream project that kkFileView wraps via JODConverter; understanding its format support and limitations is essential
• apache/poi — Direct dependency for XLSX/XLS parsing; customizing Office preview behavior requires knowledge of POI internals
• bytedeco/javacv — Wraps FFmpeg and OpenCV for video/3D preview; used by kkFileView to avoid reinventing media handling
• LibreOffice/impress — LibreOffice's presentation module; kkFileView relies on its stability for PPT/ODP conversions
• xuxueli/xxl-job — Not directly related but commonly paired with kkFileView for distributed async file processing in large-scale deployments

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive E2E test coverage for file format preview validation

The repo has nightly-e2e.yml and pr-e2e-mvp.yml workflows but doc/e2e-improvement-checklist.md suggests incomplete coverage. Given the project supports 50+ file formats (doc, docx, xls, xlsx, ppt, pptx, pdf, psd, vsd, bpmn, xmind, zip, audio, video, 3ds, dcm, cad, etc.), there's a critical gap: no visible automated tests validating that each preview type renders correctly. Add parameterized E2E tests in a new .github/workflows/e2e-format-matrix.yml that tests each format listed in README.md against actual sample files.

• [ ] Create test/e2e/formats directory with sample files for each major format category
• [ ] Update .github/workflows/e2e-format-matrix.yml to run matrix tests across: office docs, images, media, archives, and specialized formats
• [ ] Add validation script in .github/scripts/ to verify preview output against expected mime-types and rendering
• [ ] Document test coverage status in doc/e2e-improvement-checklist.md with results for all 50+ formats

Extract and document deployment scripts for Windows/Linux into server/deployment module

The repo has .github/scripts/deploy_windows_winrm.py and remote_windows_deploy.ps1 alongside .workflow/MasterPipeline.yml and doc/ci-auto-deploy.md, but these deployment utilities are scattered and lack clear documentation. New contributors struggle to understand the deployment pipeline. Create a unified server/deployment/ directory with structured scripts and a DEPLOYMENT.md guide covering both Windows and Linux deployment paths.

• [ ] Create server/deployment/ directory structure with windows/ and linux/ subdirectories
• [ ] Refactor .github/scripts/deploy_windows_winrm.py and remote_windows_deploy.ps1 into server/deployment/windows/
• [ ] Create equivalent server/deployment/linux/deploy.sh script (currently missing)
• [ ] Write server/DEPLOYMENT.md documenting: prerequisites, LibreOfficePortable setup, environment variables, and troubleshooting for both platforms

Add Docker image build validation and security scanning to CI pipeline

The repo has Dockerfile and docker/kkfileview-base/Dockerfile with fonts/.gitkeep but no CI validation that images build correctly or pass security scans. With Java 21 and multiple native dependencies (LibreOffice, FFmpeg, OpenCV), supply chain security is critical. Add a GitHub Actions workflow to build and scan Docker images on every PR.

• [ ] Create .github/workflows/docker-build-security.yml that builds both Dockerfile and docker/kkfileview-base/Dockerfile on PR
• [ ] Integrate Trivy vulnerability scanning step to check for CVEs in base image and dependencies
• [ ] Add docker/kkfileview-base/README.md documentation about supported base image versions and security update frequency
• [ ] Create .dockerignore to exclude unnecessary files (doc/img/, .git/, test files) from image context

• Add unit tests for PdfPreviewImpl and ImagePreviewImpl converters in src/test/; currently E2E-only coverage exists per e2e-improvement-checklist.md
• Document REST API endpoint signatures and MIME type mappings in doc/ (README.md mentions REST API but lacks OpenAPI spec or endpoint catalog)
• Create example Docker Compose config in doc/ showing kkfileview + reverse proxy (nginx) + file storage (S3/MinIO) for typical SaaS deployment pattern

• Critical · Outdated Spring Boot Version with Known Vulnerabilities — pom.xml - spring.boot.version property. Spring Boot 3.5.6 is not the latest stable version and may contain known security vulnerabilities. Spring Boot 3.x versions have had multiple security patches released after 3.5.6. Fix: Update to the latest stable Spring Boot 3.x version (3.5.x or higher if available). Review Spring Security advisories at https://spring.io/security for patched versions.
• High · Outdated PDF Processing Library — pom.xml - pdfbox.version property. PDFBox 3.0.6 may have known vulnerabilities. PDF processing libraries are frequent targets for exploitation due to the complexity of PDF parsing. Fix: Update PDFBox to the latest stable version and monitor Apache PDFBox security advisories regularly.
• High · Outdated Apache POI Library — pom.xml - poi.version property. POI 5.2.5 is not the latest version. POI handles Microsoft Office document parsing, which is a critical component for security given the file upload/processing nature of this application. Fix: Update Apache POI to version 5.3.0 or later to address known security vulnerabilities in Office document parsing.
• High · Insecure Docker Base Image Configuration — Dockerfile - FROM statement. The Dockerfile references 'keking/kkfileview-base:5.0.0' without specifying exact digest or verifying image source. This creates supply chain risk and allows potential image tampering. Fix: Use image digest-based references (e.g., FROM keking/kkfileview-base@sha256:...) and regularly scan base images for vulnerabilities using tools like Trivy or Grype.
• High · Missing Security Headers in Application Configuration — application.properties (referenced in Dockerfile but not provided). No visible security headers configuration (HSTS, CSP, X-Frame-Options, etc.) in the default Spring Boot setup for a file preview application that may be exposed to the internet. Fix: Configure Spring Security to add HTTP security headers. Implement SecurityFilterChain with .headers().contentSecurityPolicy(), .xssProtection(), .frameOptions().deny(), etc.
• High · Potential File Upload/Processing Vulnerability — Core application logic (not visible in provided structure). Application accepts multiple file formats (.doc, .docx, .xls, .pdf, etc.) and processes them via external tools (LibreOffice, ffmpeg). This creates risk of arbitrary code execution through malicious files without proper validation. Fix: Implement strict file type validation (magic bytes verification), sandboxing for document conversion processes, file size limits, and quarantine malicious files. Use AppArmor or seccomp profiles for subprocess execution.
• High · Insecure FFmpeg Integration — pom.xml - ffmpeg.version property. FFmpeg 7.1.1 is used for video processing. FFmpeg has history of vulnerabilities in media parsing. No indication of input validation or sandboxing for untrusted video files. Fix: Validate video files before processing, run FFmpeg in sandboxed environment, implement timeout and resource limits, keep FFmpeg updated to latest patch versions.
• Medium · Missing Authentication/Authorization in Configuration — application.properties (not provided) and Docker configuration. No visible authentication or authorization mechanisms in the provided configuration. File preview service should restrict access to authorized users only. Fix: Implement Spring Security with authentication (OAuth2, SAML, or basic auth) and authorization controls. Require API key or user authentication for file preview endpoints.
• Medium · Hardcoded Java Version and Encoding — pom.xml - java.version property and Dockerfile ENTRYPOINT. Java 21 is specified in pom.xml and Dockerfile. While not a vulnerability itself, using very new versions in production requires careful compatibility testing. UTF-8 encoding is hardcoded in Dockerfile. Fix: Use Java LTS versions (21 is LTS but test thoroughly). Make file encoding configurable rather than hardcoded.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.