From 4b44ab7c3deae70519feaa6d01ae7cf71d97ecc7 Mon Sep 17 00:00:00 2001 From: Ahmet Abdullah Gultekin Date: Thu, 28 May 2026 08:32:49 +0000 Subject: [PATCH 1/2] docs: refresh stale claims + archive pre-prod planning docs (freshness audit 2026-05-28) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Archive (git mv → archive/2026-05-28/): - 04-api/SERVICES_OVERVIEW.md: Nov-2025, called Java API "Kotlin", used H2 in-memory DB - 05-testing/test-report.md: Jan-2025 synthetic static analysis, cited superseded HS256 JWT - modules/biometric-processor.md: "NOT STARTED" status — service is live - modules/identity-core-api.md: "Basic CRUD only" — superseded by MODULE_STRUCTURE.md - modules/client-apps.md, modules/web-app.md, modules/documentation.md: pre-implementation plans superseded by MODULE_STRUCTURE.md In-place edits: - 02-architecture/MODULE_STRUCTURE.md: Flyway "(6 versions)" → "(60 versions)"; archive path 99-archive/ → archive/ - 02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md: status "Pre-Implementation" → "Implemented (Phase 4 complete 2026-05-16)"; MobileFaceNet note + geometry-512 client path - 02-architecture/diagrams/README.md: remove dead links PLANTUML_DIAGRAMS_PART2.md, PLANTUML_DIAGRAMS_FIXED.md, SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md, DESIGN_AUDIT_REPORT.md - 06-deployment/README.md: "not yet configured" → prod live on Hetzner CX43 + Docker Compose + Traefik; ./gradlew bootRun → ./mvnw spring-boot:run - 06-deployment/deployment-guide.md: 5 repos → 7 submodules/1 parent (8 total); biometric-processor port 8000 → 8001; ./gradlew → ./mvnw for identity-core-api sections - 06-deployment/START_ALL_SERVICES.md: ./gradlew.bat clean bootJar → ./mvnw clean package for identity-core-api - 07-status/README.md: replaced stale progress bars + broken links with pointer to parent ROADMAP.md - 04-api/README.md, 04-api/BACKEND_FRONTEND_INTEGRATION.md, 04-api/backend-api/SPRINGDOC_SETUP.md: ./gradlew → ./mvnw for identity-core-api - 01-getting-started/API_INTEGRATION_QUICKSTART.md, METRICS_COLLECTION_GUIDE.md: ./gradlew → ./mvnw for identity-core-api - 01-getting-started/GETTING_STARTED.md: hardcoded C:\Users\ahabg\... → path/to/FIVUCSAS - 05-testing/README.md, HOW_TO_TEST_APPS.md, MOBILE_TESTING_GUIDE.md: ./gradlew bootRun → ./mvnw spring-boot:run for identity-core-api; hardcoded paths fixed - README.md: fixed links to archived SERVICES_OVERVIEW.md and test-report.md - archive/README.md: document 2026-05-28 batch Co-Authored-By: Claude Opus 4.7 (1M context) --- .../API_INTEGRATION_QUICKSTART.md | 2 +- 01-getting-started/GETTING_STARTED.md | 10 +-- .../METRICS_COLLECTION_GUIDE.md | 4 +- .../BIOMETRIC_ENGINE_ARCHITECTURE.md | 4 +- 02-architecture/MODULE_STRUCTURE.md | 4 +- 02-architecture/diagrams/README.md | 6 +- 04-api/BACKEND_FRONTEND_INTEGRATION.md | 2 +- 04-api/README.md | 4 +- 04-api/backend-api/SPRINGDOC_SETUP.md | 10 +-- 05-testing/HOW_TO_TEST_APPS.md | 4 +- 05-testing/MOBILE_TESTING_GUIDE.md | 8 +-- 05-testing/README.md | 4 +- 06-deployment/README.md | 12 +--- 06-deployment/START_ALL_SERVICES.md | 2 +- 06-deployment/deployment-guide.md | 36 +++++----- 07-status/README.md | 67 +++---------------- README.md | 6 +- .../2026-05-28}/SERVICES_OVERVIEW.md | 0 .../2026-05-28}/biometric-processor.md | 0 .../2026-05-28}/client-apps.md | 0 .../2026-05-28}/documentation.md | 0 .../2026-05-28}/identity-core-api.md | 0 .../2026-05-28}/test-report.md | 0 {modules => archive/2026-05-28}/web-app.md | 0 archive/README.md | 12 ++++ 25 files changed, 76 insertions(+), 121 deletions(-) rename {04-api => archive/2026-05-28}/SERVICES_OVERVIEW.md (100%) rename {modules => archive/2026-05-28}/biometric-processor.md (100%) rename {modules => archive/2026-05-28}/client-apps.md (100%) rename {modules => archive/2026-05-28}/documentation.md (100%) rename {modules => archive/2026-05-28}/identity-core-api.md (100%) rename {05-testing => archive/2026-05-28}/test-report.md (100%) rename {modules => archive/2026-05-28}/web-app.md (100%) diff --git a/01-getting-started/API_INTEGRATION_QUICKSTART.md b/01-getting-started/API_INTEGRATION_QUICKSTART.md index c0919e2..3779cf5 100644 --- a/01-getting-started/API_INTEGRATION_QUICKSTART.md +++ b/01-getting-started/API_INTEGRATION_QUICKSTART.md @@ -7,7 +7,7 @@ ```bash cd identity-core-api export JWT_SECRET=your-dev-secret-key-change-in-production -./gradlew bootRun --args='--spring.profiles.active=dev' +./mvnw spring-boot:run --args='--spring.profiles.active=dev' ``` Backend ready at: `http://localhost:8080` diff --git a/01-getting-started/GETTING_STARTED.md b/01-getting-started/GETTING_STARTED.md index 99f9797..b8bacd0 100644 --- a/01-getting-started/GETTING_STARTED.md +++ b/01-getting-started/GETTING_STARTED.md @@ -40,7 +40,7 @@ Before running the mobile/desktop apps, ensure backend services are running: ```bash # Navigate to project root -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS +cd path/to/FIVUCSAS # Start all backend services docker-compose up -d @@ -63,7 +63,7 @@ docker-compose ps ```bash # Navigate to mobile-app directory -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS\client-apps +cd path/to/FIVUCSAS/client-apps # Build Debug APK ./gradlew :androidApp:assembleDebug @@ -100,7 +100,7 @@ adb install -r androidApp\build\outputs\apk\debug\androidApp-debug.apk #### Method A: Run in Development Mode ```bash -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS\client-apps +cd path/to/FIVUCSAS/client-apps # Run desktop app ./gradlew :desktopApp:run @@ -140,7 +140,7 @@ Output location: #### Step 1: Generate Xcode Framework ```bash -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS\client-apps +cd path/to/FIVUCSAS/client-apps # Install CocoaPods (if not installed) sudo gem install cocoapods @@ -176,7 +176,7 @@ open iosApp.xcworkspace ```bash # Terminal 1: Start services -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS +cd path/to/FIVUCSAS docker-compose up # Verify services diff --git a/01-getting-started/METRICS_COLLECTION_GUIDE.md b/01-getting-started/METRICS_COLLECTION_GUIDE.md index 024669a..5151492 100644 --- a/01-getting-started/METRICS_COLLECTION_GUIDE.md +++ b/01-getting-started/METRICS_COLLECTION_GUIDE.md @@ -196,8 +196,8 @@ SELECT pg_size_pretty(pg_relation_size('biometric_data_embedding_idx')); ```bash # For Identity Core (Java/Spring Boot) cd identity-core-api -./gradlew test jacocoTestReport -# Report generated at: build/reports/jacoco/test/html/index.html +./mvnw test jacoco:report +# Report generated at: target/site/jacoco/index.html # For Biometric Processor (Python/FastAPI) cd biometric-processor diff --git a/02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md b/02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md index 9095e7a..e2a20bc 100644 --- a/02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md +++ b/02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md @@ -2,7 +2,7 @@ **Version:** 2.0 **Date:** 2026-03-19 -**Status:** Design Document (Pre-Implementation) +**Status:** Implemented (Phase 4 complete 2026-05-16) **Source of Truth:** `biometric-processor/demo_local_fast.py` (2551 lines) --- @@ -278,7 +278,7 @@ Nice to have. Server-side alternatives exist for all of these. | Component | Responsibility | Server Fallback | |-----------|---------------|-----------------| | `PassiveLivenessDetector` | Texture/color/moire liveness scoring | Server-side liveness via `biometric-processor` is the primary authority. Client-side is supplementary. Gabor convolution is expensive; defer to Phase 3. | -| `EmbeddingComputer` | ONNX MobileFaceNet face embeddings | Server-side DeepFace embedding via REST API | +| `EmbeddingComputer` | ONNX face embeddings | Server-side DeepFace embedding via REST API. **Note:** MobileFaceNet was removed per ADR 0003 (2026-04-18); the active client path is geometry-512 (landmark-based fallback). | | `CardDetector` | ONNX YOLO card detection | Server-side YOLO (current production path) | --- diff --git a/02-architecture/MODULE_STRUCTURE.md b/02-architecture/MODULE_STRUCTURE.md index 9cf9d74..edc850d 100644 --- a/02-architecture/MODULE_STRUCTURE.md +++ b/02-architecture/MODULE_STRUCTURE.md @@ -82,7 +82,7 @@ graph TD **Contains:** - `src/main/java/` - Hexagonal Architecture implementation -- `src/main/resources/db/migration/` - Flyway migrations (6 versions) +- `src/main/resources/db/migration/` - Flyway migrations (60 versions) - `src/test/` - JUnit 5 + Mockito tests --- @@ -160,7 +160,7 @@ docs/ ├── 05-testing/ # Testing guides ├── 06-deployment/ # Deployment guides ├── 07-status/ # Status reports -└── 99-archive/ # Historical documents +└── archive/ # Historical documents ``` --- diff --git a/02-architecture/diagrams/README.md b/02-architecture/diagrams/README.md index bb45290..03e78f0 100644 --- a/02-architecture/diagrams/README.md +++ b/02-architecture/diagrams/README.md @@ -54,9 +54,7 @@ Professional UML and PlantUML diagrams for the FIVUCSAS platform. ## Source Files PlantUML source files: -- **[PLANTUML_DIAGRAMS.md](PLANTUML_DIAGRAMS.md)** - PlantUML diagrams part 1 -- **[PLANTUML_DIAGRAMS_PART2.md](PLANTUML_DIAGRAMS_PART2.md)** - PlantUML diagrams part 2 -- **[PLANTUML_DIAGRAMS_FIXED.md](PLANTUML_DIAGRAMS_FIXED.md)** - Fixed PlantUML diagrams +- **[PLANTUML_DIAGRAMS.md](PLANTUML_DIAGRAMS.md)** - PlantUML diagram sources ## Diagram Tools @@ -68,8 +66,6 @@ These diagrams were created using: These diagrams are referenced throughout the documentation: - [Architecture Analysis](../ARCHITECTURE_ANALYSIS.md) -- [System Design](../SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md) -- [Design Audit](../DESIGN_AUDIT_REPORT.md) --- diff --git a/04-api/BACKEND_FRONTEND_INTEGRATION.md b/04-api/BACKEND_FRONTEND_INTEGRATION.md index c2f0108..d36f17b 100644 --- a/04-api/BACKEND_FRONTEND_INTEGRATION.md +++ b/04-api/BACKEND_FRONTEND_INTEGRATION.md @@ -438,7 +438,7 @@ cd identity-core-api export JWT_SECRET=your-secret-key-here # Run with development profile -./gradlew bootRun --args='--spring.profiles.active=dev' +./mvnw spring-boot:run --args='--spring.profiles.active=dev' ``` Backend will be available at: `http://localhost:8080` diff --git a/04-api/README.md b/04-api/README.md index 13cc0fd..571c4d4 100644 --- a/04-api/README.md +++ b/04-api/README.md @@ -14,7 +14,7 @@ Interactive API documentation for FIVUCSAS services. **Note:** Start the backend first: ```bash cd identity-core-api -./gradlew bootRun +./mvnw spring-boot:run ``` ### Biometric Service (FastAPI) @@ -33,7 +33,7 @@ uvicorn app.main:app --reload --port 8001 ## Reference Documentation -- **[SERVICES_OVERVIEW.md](SERVICES_OVERVIEW.md)** - Overview of service capabilities +- **[SERVICES_OVERVIEW.md](../archive/2026-05-28/SERVICES_OVERVIEW.md)** - Service capabilities overview (archived Nov-2025 snapshot) - **[BACKEND_REVIEW.md](BACKEND_REVIEW.md)** - Backend code review ### Implementation Guides diff --git a/04-api/backend-api/SPRINGDOC_SETUP.md b/04-api/backend-api/SPRINGDOC_SETUP.md index 4bbe561..0f1f596 100644 --- a/04-api/backend-api/SPRINGDOC_SETUP.md +++ b/04-api/backend-api/SPRINGDOC_SETUP.md @@ -30,9 +30,11 @@ dependencies { } ``` +**Note:** identity-core-api uses Maven (`./mvnw`), not Gradle. + **Test:** ```bash -./gradlew clean build +./mvnw clean package -DskipTests # Should compile successfully ``` @@ -962,7 +964,7 @@ public class AuthResponse { ```bash # Start the backend cd identity-core-api -./gradlew bootRun +./mvnw spring-boot:run ``` **Access Points:** @@ -1011,10 +1013,10 @@ Once implemented, you'll have: **Solution:** ```bash # Check if dependency is added -./gradlew dependencies | grep springdoc +./mvnw dependency:tree | grep springdoc # Verify application starts -./gradlew bootRun | grep "Swagger" +./mvnw spring-boot:run | grep "Swagger" ``` ### Issue: Endpoints not appearing diff --git a/05-testing/HOW_TO_TEST_APPS.md b/05-testing/HOW_TO_TEST_APPS.md index 54732db..2b57c4e 100644 --- a/05-testing/HOW_TO_TEST_APPS.md +++ b/05-testing/HOW_TO_TEST_APPS.md @@ -93,7 +93,7 @@ adb devices **Terminal 1 - Identity Core API** ```bash cd identity-core-api -./gradlew.bat bootRun +./mvnw spring-boot:run # Should start on http://localhost:8080 ``` @@ -409,7 +409,7 @@ cd mobile-app **To test with full system:** ```bash # Terminal 1 -cd identity-core-api && ./gradlew.bat bootRun +cd identity-core-api && ./mvnw spring-boot:run # Terminal 2 cd biometric-processor && venv\Scripts\activate && uvicorn app.main:app --reload --port 8001 diff --git a/05-testing/MOBILE_TESTING_GUIDE.md b/05-testing/MOBILE_TESTING_GUIDE.md index 70693a0..7a39abe 100644 --- a/05-testing/MOBILE_TESTING_GUIDE.md +++ b/05-testing/MOBILE_TESTING_GUIDE.md @@ -96,13 +96,13 @@ netsh advfirewall firewall show rule name="FastAPI Biometric" **Terminal 1 - Spring Boot:** ```powershell -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS\identity-core-api -.\gradlew.bat bootRun +cd path/to/FIVUCSAS/identity-core-api +./mvnw spring-boot:run ``` **Terminal 2 - FastAPI:** ```powershell -cd C:\Users\ahabg\OneDrive\Belgeler\GitHub\FIVUCSAS\biometric-processor +cd path/to/FIVUCSAS/biometric-processor .\venv\Scripts\Activate.ps1 python -m uvicorn app.main:app --host 0.0.0.0 --port 8001 ``` @@ -395,7 +395,7 @@ netsh advfirewall firewall add rule name="FIVUCSAS" dir=in action=allow protocol # Start Spring Boot cd identity-core-api -.\gradlew.bat bootRun +./mvnw spring-boot:run # In another terminal - Start FastAPI cd biometric-processor diff --git a/05-testing/README.md b/05-testing/README.md index 64d4bc1..a269217 100644 --- a/05-testing/README.md +++ b/05-testing/README.md @@ -15,8 +15,8 @@ Testing guides and test reports for FIVUCSAS. ### Backend Tests ```bash cd identity-core-api -./gradlew test -./gradlew test --tests "com.fivucsas.identity.*" +./mvnw test +./mvnw test -Dtest="com.fivucsas.identity.*" ``` ### Mobile App Tests diff --git a/06-deployment/README.md b/06-deployment/README.md index 886eeac..84d4b05 100644 --- a/06-deployment/README.md +++ b/06-deployment/README.md @@ -15,7 +15,7 @@ See [START_ALL_SERVICES.md](START_ALL_SERVICES.md) for detailed instructions. ### Start Backend API ```bash cd identity-core-api -./gradlew bootRun +./mvnw spring-boot:run # Access: http://localhost:8080 ``` @@ -35,15 +35,7 @@ cd mobile-app ## Production Deployment -⚠️ Production deployment not yet configured. Coming soon. - -**Planned Production Setup:** -- PostgreSQL database (replacing H2 in-memory) -- Redis cache and message queue -- Docker containers -- Kubernetes orchestration (optional) -- NGINX reverse proxy -- Monitoring and logging +Production is live on Hetzner CX43 via Docker Compose + Traefik (api.fivucsas.com). PostgreSQL with pgvector, Redis, and Loki/Grafana monitoring are all running. ## Environment Configuration diff --git a/06-deployment/START_ALL_SERVICES.md b/06-deployment/START_ALL_SERVICES.md index f28c451..1f6e8f4 100644 --- a/06-deployment/START_ALL_SERVICES.md +++ b/06-deployment/START_ALL_SERVICES.md @@ -176,7 +176,7 @@ pip install pydantic-settings ### ❌ "Cannot find JAR file" ```powershell cd identity-core-api -.\gradlew.bat clean bootJar +./mvnw clean package -DskipTests ``` ### ❌ Desktop app won't start diff --git a/06-deployment/deployment-guide.md b/06-deployment/deployment-guide.md index 849853f..ab42891 100644 --- a/06-deployment/deployment-guide.md +++ b/06-deployment/deployment-guide.md @@ -28,15 +28,19 @@ ### Module Repositories -The project is split into **5 independent repositories**: +The project uses **7 submodules under 1 parent repository (8 repos total)**. See [MODULE_STRUCTURE.md](../02-architecture/MODULE_STRUCTURE.md) for the full list and current status. -| Repository | Purpose | Technology | Status | -|-----------|---------|-----------|--------| -| **identity-core-api** | Backend API & Auth | Spring Boot (Java) | ⚠️ 60% | -| **web-app** | Admin Dashboard | React + TypeScript | ✅ 100% UI | -| **biometric-processor** | AI/ML Service | FastAPI (Python) | ❌ 0% | -| **mobile-app** | Desktop + Mobile Apps | Kotlin Multiplatform | ⚠️ 96% Desktop | -| **docs** | Documentation | Markdown + Docusaurus | ❌ Basic | +Key submodules: + +| Repository | Purpose | Technology | +|-----------|---------|-----------| +| **identity-core-api** | Backend API & Auth | Java 21 / Spring Boot 3.4.7 (Maven) | +| **web-app** | Admin Dashboard | React 18 + TypeScript + Vite | +| **biometric-processor** | AI/ML Service | Python / FastAPI (port 8001) | +| **client-apps** | Desktop + Mobile Apps | Kotlin Multiplatform | +| **spoof-detector** | PAD algorithms | Python | +| **practice-and-test** | R&D & Experiments | Mixed | +| **docs** | Documentation | Markdown | ### Why Separate Repositories? @@ -103,7 +107,7 @@ The project is split into **5 independent repositories**: **Repository**: https://github.com/Rollingcat-Software/biometric-processor **Technology**: FastAPI (Python 3.10+) -**Port**: 8000 +**Port**: 8001 **Database**: PostgreSQL 16 (pgvector) **Responsibilities**: @@ -187,7 +191,7 @@ The project is split into **5 independent repositories**: │ │ identity-core-api │◄─────────►│ biometric- │ │ │ │ (Spring Boot) │ Webhooks │ processor │ │ │ │ Port: 8080 │ │ (FastAPI) │ │ -│ └──────┬─────────────┘ │ Port: 8000 │ │ +│ └──────┬─────────────┘ │ Port: 8001 │ │ │ │ └──────┬───────────┘ │ │ │ │ │ │ ┌──────▼────────┐ ┌───────▼──────────┐ │ @@ -214,7 +218,7 @@ identity-core-api:8080/api/v1 ``` identity-core-api ↓ POST /biometric/enroll -biometric-processor:8000/enroll +biometric-processor:8001/enroll ↓ Returns job ID ↓ Processes async ↓ Webhook callback @@ -514,17 +518,17 @@ pip install -r requirements.txt cat > .env << EOF DATABASE_URL=postgresql://postgres:postgres@localhost:5432/fivucsas REDIS_URL=redis://localhost:6379/0 -APP_PORT=8000 +APP_PORT=8001 EOF # Start FastAPI server -uvicorn main:app --reload --port 8000 +uvicorn main:app --reload --port 8001 # Start Celery worker (separate terminal) celery -A app.worker worker --loglevel=info # Test -curl http://localhost:8000/health +curl http://localhost:8001/health # Expected: {"status":"ok","version":"1.0.0"} ``` @@ -550,7 +554,7 @@ cd ../mobile-app # Check all services curl http://localhost:8080/api/v1/auth/health # identity-core-api curl http://localhost:5173 # web-app (should see HTML) -curl http://localhost:8000/health # biometric-processor +curl http://localhost:8001/health # biometric-processor # Check databases docker ps | grep postgres # PostgreSQL running @@ -904,7 +908,7 @@ Use Prometheus + Grafana: ## 📈 Success Criteria ### Development Complete -- ✅ All 5 repositories have code and tests +- ✅ All repositories have code and tests - ✅ All services run locally without errors - ✅ Integration tests pass - ✅ Documentation complete diff --git a/07-status/README.md b/07-status/README.md index 83a7a55..748616a 100644 --- a/07-status/README.md +++ b/07-status/README.md @@ -1,68 +1,17 @@ # Project Status -Current project status and progress reports. +For the authoritative, up-to-date project status and roadmap, see the parent repository: -## Current Status +**[FIVUCSAS/ROADMAP.md](https://github.com/Rollingcat-Software/FIVUCSAS/blob/master/ROADMAP.md)** — current phase, backlog, and milestone tracking. -**[PROJECT_STATUS.md](PROJECT_STATUS.md)** - Authoritative project status +## Historical Status Documents -## Overall Progress: 65% Complete +Archived pre-production planning documents are in [../archive/](../archive/): -``` -Mobile App: ████████████████████ 95% - Production Ready -Backend API: ███████████████░░░░░ 78% - Minor fixes needed -Biometric: ████████████████░░░░ 80% - Core features complete -Documentation: ██████████████████░░ 90% - Comprehensive -Web Dashboard: ░░░░░░░░░░░░░░░░░░░░ 0% - Not started -Deployment: ░░░░░░░░░░░░░░░░░░░░ 0% - Not started -``` - -## Status Documents - -| File | Description | -|------|-------------| -| [PROJECT_STATUS.md](PROJECT_STATUS.md) | Authoritative project status | -| [FINAL_COMPLETION_REPORT.md](FINAL_COMPLETION_REPORT.md) | Completion summary | -| [KMP_IMPLEMENTATION_STATUS.md](KMP_IMPLEMENTATION_STATUS.md) | Kotlin Multiplatform status | -| [MOBILE_APP_STATUS.md](MOBILE_APP_STATUS.md) | Mobile app status | - -## What's Done (65%) - -### Mobile App - 95% -- Kotlin Multiplatform structure -- Clean Architecture (MVVM) -- Admin module (user management) -- Kiosk module (face verification) -- 90% code sharing across platforms - -### Backend API - 78% -- Spring Boot 3.2+ setup -- User management endpoints -- Authentication endpoints -- Biometric integration -- H2 database - -### Biometric Service - 80% -- FastAPI setup -- Face embedding extraction (VGG-Face) -- Face verification (cosine similarity) -- Integration with backend - -### Documentation - 90% -- Comprehensive guides -- Architecture documentation -- 35+ diagrams -- Professional organization - -## What's Not Started (15%) - -- Web dashboard (React 18) -- Production deployment (PostgreSQL, Redis, Docker) -- Monitoring and logging - -## Historical Status - -See [../99-archive/](../99-archive/) for historical status reports and completed milestones. +- `archive/2026-04-16/FINAL_COMPLETION_REPORT.md` +- `archive/2026-04-16/KMP_IMPLEMENTATION_STATUS.md` +- `archive/2026-04-16/MOBILE_APP_STATUS.md` +- `archive/2026-04-16/IMPLEMENTATION_STATUS_REPORT.md` --- diff --git a/README.md b/README.md index e9ce6ea..ee897a5 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ - **OpenAPI JSON:** [http://localhost:8001/openapi.json](http://localhost:8001/openapi.json) #### Reference Documentation -- [SERVICES_OVERVIEW.md](04-api/SERVICES_OVERVIEW.md) - Service capabilities overview +- [SERVICES_OVERVIEW.md](archive/2026-05-28/SERVICES_OVERVIEW.md) - Service capabilities overview (archived Nov-2025 snapshot) - [BACKEND_REVIEW.md](04-api/BACKEND_REVIEW.md) - Backend code review - [Backend SpringDoc Setup](04-api/backend-api/SPRINGDOC_SETUP.md) - SpringDoc OpenAPI implementation - [Biometric FastAPI Setup](04-api/biometric-service/FASTAPI_SETUP.md) - FastAPI documentation setup @@ -86,7 +86,7 @@ **Testing guides and test reports** - [TESTING_GUIDE.md](05-testing/TESTING_GUIDE.md) - Complete testing guide (908 lines) - [MOBILE_TESTING_GUIDE.md](05-testing/MOBILE_TESTING_GUIDE.md) - Mobile app testing -- [baseline-results.md](05-testing/baseline-results.md) / [integration-testing.md](05-testing/integration-testing.md) / [load-testing.md](05-testing/load-testing.md) / [test-report.md](05-testing/test-report.md) +- [baseline-results.md](05-testing/baseline-results.md) / [integration-testing.md](05-testing/integration-testing.md) / [load-testing.md](05-testing/load-testing.md) / [test-report.md](archive/2026-05-28/test-report.md) (archived Jan-2025 synthetic) ### 6️⃣ [Deployment](06-deployment/) **Deployment and operations guides** @@ -242,7 +242,7 @@ cd client-apps && ./gradlew :shared:test **For API Integration:** 1. [Backend API Docs](http://localhost:8080/swagger-ui.html) 2. [Biometric Service Docs](http://localhost:8001/docs) -3. [Services Overview](04-api/SERVICES_OVERVIEW.md) +3. [Services Overview](archive/2026-05-28/SERVICES_OVERVIEW.md) (archived Nov-2025 snapshot) **For Testing:** 1. [Testing Guide](05-testing/TESTING_GUIDE.md) diff --git a/04-api/SERVICES_OVERVIEW.md b/archive/2026-05-28/SERVICES_OVERVIEW.md similarity index 100% rename from 04-api/SERVICES_OVERVIEW.md rename to archive/2026-05-28/SERVICES_OVERVIEW.md diff --git a/modules/biometric-processor.md b/archive/2026-05-28/biometric-processor.md similarity index 100% rename from modules/biometric-processor.md rename to archive/2026-05-28/biometric-processor.md diff --git a/modules/client-apps.md b/archive/2026-05-28/client-apps.md similarity index 100% rename from modules/client-apps.md rename to archive/2026-05-28/client-apps.md diff --git a/modules/documentation.md b/archive/2026-05-28/documentation.md similarity index 100% rename from modules/documentation.md rename to archive/2026-05-28/documentation.md diff --git a/modules/identity-core-api.md b/archive/2026-05-28/identity-core-api.md similarity index 100% rename from modules/identity-core-api.md rename to archive/2026-05-28/identity-core-api.md diff --git a/05-testing/test-report.md b/archive/2026-05-28/test-report.md similarity index 100% rename from 05-testing/test-report.md rename to archive/2026-05-28/test-report.md diff --git a/modules/web-app.md b/archive/2026-05-28/web-app.md similarity index 100% rename from modules/web-app.md rename to archive/2026-05-28/web-app.md diff --git a/archive/README.md b/archive/README.md index edab1a9..e4fcfd8 100644 --- a/archive/README.md +++ b/archive/README.md @@ -15,3 +15,15 @@ Bulk cleanup. Moved ~45 files out of the public docs tree because they were: - **Presentation / prep** — `PRESENTATION_COMPLETE_GUIDE`, `PRESENTATION_SPEECHES`, `SCREENSHOTS_NEEDED`, `TASK_LOG_TEMPLATE`, `ANALYTICS_PLAN` (root; lives at `docs/plans/ANALYTICS_PLAN.md`). All moves via `git mv` — authorship and timestamps preserved. + +## 2026-05-28 + +Freshness audit. Moved 7 files that were pre-implementation planning docs contradicted by current repo state: + +- **`SERVICES_OVERVIEW.md`** (from `04-api/`) — Nov-2025 snapshot, called Java API "Kotlin", used H2 in-memory DB. +- **`test-report.md`** (from `05-testing/`) — Jan-2025 synthetic static-analysis report, cited HS256 JWT which has since been superseded by RS256 default. +- **`modules/biometric-processor.md`** — Pre-implementation plan, status "NOT STARTED"; service is live. +- **`modules/identity-core-api.md`** — Pre-implementation plan, status "Basic CRUD only"; superseded by MODULE_STRUCTURE.md. +- **`modules/client-apps.md`** — Pre-implementation plan, superseded by MODULE_STRUCTURE.md. +- **`modules/web-app.md`** — Pre-implementation plan, superseded by MODULE_STRUCTURE.md. +- **`modules/documentation.md`** — Pre-implementation plan, superseded by MODULE_STRUCTURE.md. From 6f91fe0074e592279e0cd0dfb9fe96843aec27ae Mon Sep 17 00:00:00 2001 From: Ahmet Abdullah Gultekin Date: Thu, 28 May 2026 08:48:19 +0000 Subject: [PATCH 2/2] docs: fix pre-existing dead links surfaced by link-check (freshness audit 2026-05-28) Co-Authored-By: Claude Opus 4.7 (1M context) --- 04-api/README.md | 2 +- 05-testing/README.md | 4 ++-- 06-deployment/README.md | 8 ++++---- 06-deployment/START_ALL_SERVICES.md | 2 +- README.md | 22 +++++++++++----------- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/04-api/README.md b/04-api/README.md index 571c4d4..bcb8008 100644 --- a/04-api/README.md +++ b/04-api/README.md @@ -34,7 +34,7 @@ uvicorn app.main:app --reload --port 8001 ## Reference Documentation - **[SERVICES_OVERVIEW.md](../archive/2026-05-28/SERVICES_OVERVIEW.md)** - Service capabilities overview (archived Nov-2025 snapshot) -- **[BACKEND_REVIEW.md](BACKEND_REVIEW.md)** - Backend code review +- **BACKEND_REVIEW.md** - Backend code review ### Implementation Guides - **[backend-api/SPRINGDOC_SETUP.md](backend-api/SPRINGDOC_SETUP.md)** - SpringDoc OpenAPI setup for backend diff --git a/05-testing/README.md b/05-testing/README.md index a269217..d22f0a2 100644 --- a/05-testing/README.md +++ b/05-testing/README.md @@ -6,8 +6,8 @@ Testing guides and test reports for FIVUCSAS. - **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - ⭐ Complete testing guide (908 lines) - **[MOBILE_TESTING_GUIDE.md](MOBILE_TESTING_GUIDE.md)** - Mobile app testing -- **[BACKEND_TEST_REPORT.md](BACKEND_TEST_REPORT.md)** - Backend test results -- **[QUICKSTART_TEST.md](QUICKSTART_TEST.md)** - Quick testing guide +- **BACKEND_TEST_REPORT.md** - Backend test results +- **[TEST_QUICKSTART.md](TEST_QUICKSTART.md)** - Quick testing guide - **[HOW_TO_TEST_APPS.md](HOW_TO_TEST_APPS.md)** - How to test applications ## Quick Test Commands diff --git a/06-deployment/README.md b/06-deployment/README.md index 84d4b05..92e253e 100644 --- a/06-deployment/README.md +++ b/06-deployment/README.md @@ -5,8 +5,8 @@ Deployment and operations guides for FIVUCSAS. ## Local Development - **[START_ALL_SERVICES.md](START_ALL_SERVICES.md)** - How to start all services locally -- **[BACKEND_DAY_1_PLAN.md](BACKEND_DAY_1_PLAN.md)** - Backend setup plan -- **[BACKEND_NEXT_STEPS.md](BACKEND_NEXT_STEPS.md)** - Backend next steps +- **BACKEND_DAY_1_PLAN.md** - Backend setup plan +- **BACKEND_NEXT_STEPS.md** - Backend next steps ## Quick Start All Services @@ -61,8 +61,8 @@ Operator runbooks live in the `infra/` repo at `/opt/projects/infra/RUNBOOK_*.md | Runbook | Path | When to use | |---------|------|-------------| -| **Disk capacity** | [`infra/RUNBOOK_DISK.md`](../../infra/RUNBOOK_DISK.md) | Before any `docker compose build --no-cache` on the Hetzner CX43 host; on `ENOSPC` alerts. Documents the 5 defence-in-depth layers (per-container log caps, journald cap, hourly disk-guard, daily sweep, weekly aggressive prune). | -| **Audit log partitioning (pg_partman V57)** | [`infra/RUNBOOK_AUDIT_LOG_PARTMAN.md`](../../infra/RUNBOOK_AUDIT_LOG_PARTMAN.md) | When applying or reasoning about Flyway V57. pg_partman with monthly partitions, premake=12, retention 24 months; fail-soft when extension missing (`RAISE WARNING + RETURN`). Includes explicit opt-out `ALTER DATABASE identity_core SET app.skip_partman_v57='on'`. | +| **Disk capacity** | [`infra/RUNBOOK_DISK.md`](https://github.com/Rollingcat-Software/FIVUCSAS/blob/master/infra/RUNBOOK_DISK.md) | Before any `docker compose build --no-cache` on the Hetzner CX43 host; on `ENOSPC` alerts. Documents the 5 defence-in-depth layers (per-container log caps, journald cap, hourly disk-guard, daily sweep, weekly aggressive prune). | +| **Audit log partitioning (pg_partman V57)** | [`infra/RUNBOOK_AUDIT_LOG_PARTMAN.md`](https://github.com/Rollingcat-Software/FIVUCSAS/blob/master/infra/RUNBOOK_AUDIT_LOG_PARTMAN.md) | When applying or reasoning about Flyway V57. pg_partman with monthly partitions, premake=12, retention 24 months; fail-soft when extension missing (`RAISE WARNING + RETURN`). Includes explicit opt-out `ALTER DATABASE identity_core SET app.skip_partman_v57='on'`. | | **Disaster recovery** | `infra/RUNBOOK_DR.md` | Annual DR drill, or a real outage requiring restore from off-site backup. | | **Flyway repair** | `infra/RUNBOOK_FLYWAY_REPAIR.md` | When `schema_history` is out of sync with the migrations on disk. | | **Network** | `infra/RUNBOOK_NETWORK.md` | DNS, Traefik routing, firewall, VPN. | diff --git a/06-deployment/START_ALL_SERVICES.md b/06-deployment/START_ALL_SERVICES.md index 1f6e8f4..8b2c1dd 100644 --- a/06-deployment/START_ALL_SERVICES.md +++ b/06-deployment/START_ALL_SERVICES.md @@ -211,7 +211,7 @@ Once all running, access these URLs in browser: All green? You're good to go! ✅ - [ ] Terminal 1 shows: "Tomcat started on port 8080" -- [ ] Terminal 2 shows: "Uvicorn running on http://0.0.0.0:8001" +- [ ] Terminal 2 shows: "Uvicorn running on `http://0.0.0.0:8001`" - [ ] Terminal 3 shows desktop window - [ ] `curl http://localhost:8080/api/v1/auth/health` works - [ ] `curl http://localhost:8001/health` works diff --git a/README.md b/README.md index ee897a5..e9e3bc3 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ ### 0️⃣ [Meta Documentation](00-meta/) **Documentation about documentation** -- [Module Design](00-meta/module-design/) - Documentation module design and analysis +- Module Design - Documentation module design and analysis - [Project Artifacts](00-meta/project-artifacts/) - PSD, proposals, original documents - [ADD_2403.txt](00-meta/ADD_2403.txt) - Student project title page @@ -46,7 +46,7 @@ ### 2️⃣ [Architecture](02-architecture/) **System design and architectural decisions** - [ARCHITECTURE_ANALYSIS.md](02-architecture/ARCHITECTURE_ANALYSIS.md) - Complete architecture analysis -- [SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md](02-architecture/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md) - Design decisions +- SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md - Design decisions - [data-flow.md](02-architecture/data-flow.md) / [event-bus.md](02-architecture/event-bus.md) / [webhooks.md](02-architecture/webhooks.md) / [security.md](02-architecture/security.md) / [structure.md](02-architecture/structure.md) - [BIOMETRIC_ENGINE_ARCHITECTURE.md](02-architecture/BIOMETRIC_ENGINE_ARCHITECTURE.md) - Biometric engine design - [VERIFICATION_PIPELINE_ARCHITECTURE.md](02-architecture/VERIFICATION_PIPELINE_ARCHITECTURE.md) - Verification pipeline design @@ -78,7 +78,7 @@ #### Reference Documentation - [SERVICES_OVERVIEW.md](archive/2026-05-28/SERVICES_OVERVIEW.md) - Service capabilities overview (archived Nov-2025 snapshot) -- [BACKEND_REVIEW.md](04-api/BACKEND_REVIEW.md) - Backend code review +- BACKEND_REVIEW.md - Backend code review - [Backend SpringDoc Setup](04-api/backend-api/SPRINGDOC_SETUP.md) - SpringDoc OpenAPI implementation - [Biometric FastAPI Setup](04-api/biometric-service/FASTAPI_SETUP.md) - FastAPI documentation setup @@ -102,7 +102,7 @@ ### 8️⃣ [Website & Marketing](08-website/) **Landing website documentation for fivucsas.com** -- [ADD_LANDING_WEBSITE.md](08-website/ADD_LANDING_WEBSITE.md) - ⭐ **Landing website Analysis & Design Document** +- ADD_LANDING_WEBSITE.md - Landing website Analysis & Design Document - Domain: `fivucsas.com` (Hostinger) - Purpose: Marketing, branding, lead generation @@ -158,9 +158,9 @@ | **Biometric Processor** | FastAPI (Python 3.11) | ✅ 100% | [FastAPI Docs](http://localhost:8001/docs) | | **Demo GUI** | Next.js 14, TypeScript | ✅ 100% | Embedded in Biometric Processor | | **Identity Core API** | Spring Boot 3.2 (Java 21) | ⚠️ 90% | [Swagger UI](http://localhost:8080/swagger-ui.html) | -| **Web Admin Dashboard** | React 18, Material-UI | ✅ 100% | [web-app submodule](../web-app/) | +| **Web Admin Dashboard** | React 18, Material-UI | ✅ 100% | [web-app submodule](https://github.com/Rollingcat-Software/web-app) | | **Mobile/Desktop** | Kotlin Multiplatform | ⚠️ 60% (UI) | [KMP Guide](03-development/KOTLIN_MULTIPLATFORM_GUIDE.md) | -| **NFC Reader** | Kotlin, Jetpack Compose | ✅ 85% | [practice-and-test](../practice-and-test/) | +| **NFC Reader** | Kotlin, Jetpack Compose | ✅ 85% | [practice-and-test](https://github.com/Rollingcat-Software/practice-and-test) | | **Database** | PostgreSQL 16 + pgvector | ✅ 100% | [Architecture](02-architecture/ARCHITECTURE_ANALYSIS.md) | | **Cache/Queue** | Redis 7 | ✅ Ready | Docker Compose configured | @@ -191,8 +191,8 @@ Mobile/Desktop UI: ████████████░░░░░░ - **Department:** Computer Engineering - **Course:** Engineering Project (CSE4297) - **Project Type:** Multi-tenant Biometric SaaS Platform -- **Proposal:** [CSE4297_Project_Proposal.pdf](00-meta/project-artifacts/CSE4297_Project_Proposal.pdf) -- **Specification:** [PSD.docx](00-meta/project-artifacts/PSD.docx) +- **Proposal:** CSE4297_Project_Proposal.pdf +- **Specification:** PSD.docx --- @@ -270,9 +270,9 @@ This documentation follows professional software engineering principles: - **Automation** - API docs auto-generated from code (always accurate, zero maintenance) See design documentation: -- [Design Analysis](00-meta/module-design/DOCS_MODULE_DESIGN_ANALYSIS.md) -- [Professional Design](00-meta/module-design/DOCS_MODULE_PROFESSIONAL_DESIGN.md) -- [Implementation Plan](00-meta/module-design/DOCS_MODULE_IMPLEMENTATION_PLAN.md) +- Design Analysis (DOCS_MODULE_DESIGN_ANALYSIS.md) +- Professional Design (DOCS_MODULE_PROFESSIONAL_DESIGN.md) +- Implementation Plan (DOCS_MODULE_IMPLEMENTATION_PLAN.md) ---