initialization

README.md

@@ -0,0 +1,270 @@
+# Password Generator API and Web App
+
+A modern, secure password generator with a public REST API and multilingual web UI.
+The project is built with Slim PHP and focuses on production-ready password generation.
+
+## Features
+
+### Password Generators
+
+- High Entropy: cryptographically secure random passwords with configurable character sets.
+- XKCD Passphrase: memorable multi-word passphrases with language-specific wordlists.
+- Diceware: dice-style passphrases with security metadata.
+- PWGen Enhanced: pronounceable passwords with optional separator logic.
+- Passkey: Apple-style pronounceable strings using syllable patterns.
+
+### Product Capabilities
+
+- Public JSON API for password generation.
+- Responsive browser UI.
+- Localization support with runtime locale endpoint.
+- Security controls (rate limiting, CORS, secure random generation).
+- Generated OpenAPI contract.
+
+## Supported Languages
+
+- en
+- de
+- de_CH
+- fr
+- it
+- es
+- pt
+- ja
+- zh
+
+## Requirements
+
+- PHP 8.1+
+- Composer
+- Optional CLI tools for enhanced generator behavior: pwgen, xkcdpass
+
+## Quick Start
+
+### 1. Install
+
+```bash
+git clone <repository-url>
+cd password-generator
+composer install
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+cp config/config.example.json config/config.json
+mkdir -p logs
+chmod 755 logs
+```
+
+### 3. Run
+
+```bash
+composer start
+# or
+php -S localhost:8080 -t public
+```
+
+Open:
+
+- [http://localhost:8080](http://localhost:8080)
+- [http://localhost:8080/docs](http://localhost:8080/docs)
+
+## API Usage
+
+### List available generator types
+
+```bash
+curl http://localhost:8080/api/v1/passwords
+```
+
+### Generate passwords
+
+```bash
+curl -X POST http://localhost:8080/api/v1/passwords/generate \
+  -H "Content-Type: application/json" \
+  -d '{"type":"diceware","count":2,"options":{"words":6}}'
+```
+
+### Get locale payload
+
+```bash
+curl http://localhost:8080/api/v1/locales/ja
+```
+
+## Generator Option Examples
+
+### High Entropy
+
+```json
+{
+  "type": "high-entropy",
+  "count": 1,
+  "options": {
+    "length": 16,
+    "include_lowercase": true,
+    "include_uppercase": true,
+    "include_numbers": true,
+    "include_symbols": true,
+    "safe_symbols_only": false,
+    "exclude_ambiguous": false
+  }
+}
+```
+
+### XKCD Passphrase
+
+```json
+{
+  "type": "xkcdpass",
+  "count": 1,
+  "options": {
+    "words": 4,
+    "wordlist": "en",
+    "separator": "-",
+    "max_word_length": 0,
+    "space_handling": "allow",
+    "add_number": true,
+    "number_position": "end"
+  }
+}
+```
+
+### Diceware
+
+```json
+{
+  "type": "diceware",
+  "count": 1,
+  "options": {
+    "words": 6,
+    "show_dice_rolls": true,
+    "uppercase_first": false
+  }
+}
+```
+
+### PWGen Enhanced
+
+```json
+{
+  "type": "pwgen",
+  "count": 1,
+  "options": {
+    "length": 16,
+    "separator": "-_",
+    "include_numbers": true,
+    "include_capitals": true,
+    "secure_mode": false,
+    "no_ambiguous": false
+  }
+}
+```
+
+### Passkey
+
+```json
+{
+  "type": "passkey",
+  "count": 1,
+  "options": {
+    "syllables": 6
+  }
+}
+```
+
+## Configuration Notes
+
+Primary runtime configuration files:
+
+- config/config.json
+- .env
+
+Useful environment overrides:
+
+- LLM_DEFAULT_PROVIDER
+- OPENAI_API_KEY
+- CLAUDE_API_KEY
+- GEMINI_API_KEY
+- PERPLEXITY_API_KEY
+
+## OpenAPI Contract
+
+Regenerate the public API specification when routes or response schemas change:
+
+```bash
+composer generate:openapi
+# or
+php utils/generate-openapi.php
+```
+
+Generated file:
+
+- public/pwgenerator-swagger-spec.json
+
+## Docker Deployment
+
+### Build image
+
+```bash
+docker build -t password-generator:latest .
+```
+
+### Run image
+
+```bash
+docker run --rm -p 8080:8080 --name password-generator password-generator:latest
+```
+
+### Docker Compose (project-local setup)
+
+The repository includes a project-specific Compose file for local development and testing.
+
+```bash
+cp .env.example .env
+cp config/config.example.json config/config.json
+mkdir -p logs
+
+docker compose up --build -d
+```
+
+Then open:
+
+- [http://localhost:8080](http://localhost:8080)
+- [http://localhost:8080/docs](http://localhost:8080/docs)
+
+Useful commands:
+
+```bash
+docker compose logs -f password-generator
+docker compose restart password-generator
+docker compose down
+```
+
+### Docker Hub publish
+
+```bash
+docker login
+docker tag password-generator:latest YOUR_DOCKERHUB_USERNAME/password-generator:latest
+docker push YOUR_DOCKERHUB_USERNAME/password-generator:latest
+```
+
+## Testing
+
+```bash
+composer test
+```
+
+## Project Structure
+
+```text
+public/      - web root and generated OpenAPI spec
+src/         - API, generators, middleware, and utilities
+config/      - route, dependency, and app configuration
+assets/      - frontend CSS and JavaScript
+templates/   - HTML templates
+locales/     - translation files
+data/        - source wordlists
+tests/       - PHPUnit tests
+```