-----------------------------------
Getting everything up and running
-----------------------------------

On Linux x86_64 (including WSL2), install Docker with Compose, uv,
curl, tar and sha256sum, then run from this checkout:

  ./run setup

This installs the FastAPI and SvelteKit dependencies, starts local PostgreSQL
and Redis, initialises an empty database, and verifies both applications.
It preserves existing databases and does not format source files.
Local development keys are generated automatically; production credentials
are not required for this workflow.

  ./run setup:start       # Restart services without reinstalling dependencies
  ./run setup:stop        # Stop application processes before reinstalling
  ./run setup:test        # Run the full FastAPI suite in the local environment

The setup_without_formatting command remains an alias for setup.
See docs/local-development.md for prerequisites, paths, migrations and cloud use.

-----------------------------------
Troubleshooting
-----------------------------------

NOTE: An Updated Trouble Shooting Guide is now migrated into a separate document:

https://app.clickup.com/36622149/v/dc/12xku5-1376/12xku5-676

-----------------------------------
Swagger API Docs
-----------------------------------

* Swagger API Docs in JSON and YML are now available by accessing the following endpoints in Development environment:
  - /api/v1/swagger/apidocs/ (shows an interactive Swagger UI generated by Flasgger Docstrings)
  - /api/v1/swagger/apispec_1.json (returns json file format of Swagger API Doc)
  - /api/v1/swagger/download?format=json (automatically exports Swagger file in json format)
  - /api/v1/swagger/download?format=yaml (automatically exports Swaggger file in yaml format)
  - /api/v1/swagger/download?format=yml (automatically exports Swagger file in yml format)

* Swagger API Docs are also committed and available in the repo in this directories:
  - wilfie-flask-app/api-docs/swagger.json
  - wilfie-flask-app/api-docs/swagger.yml
  NOTE: Make sure to keep these copies up to date whenever there are changes in the APIs and Swagger API Docs

* SwaggerHub Auto API Mocking can also now be used for integration:
  - (Mock API URL) https://virtserver.swaggerhub.com/CJSALGO252/wilfie-ai-2/1.0
  - (Swagger Hub Playground) https://app.swaggerhub.com/apis/CJSALGO252/wilfie-ai-2/1.0

  NOTE: SwaggerHub API Auto Mocking - Setup Guide is also available in this document below:
    - https://app.clickup.com/36622149/v/dc/12xku5-1416/12xku5-716c
  
    Supported Response Content-Type:
      - application/json
      - application/xml
      - application/yaml

    Unsupported Response Content-Type:
      - text/event-stream
      - text/plain

    NOTE: The "Unsupported Response Content-Type" above are response types that cannot be mocked by the following:
      - SwaggerHub 
      - Swagger UI (Swagger API Docs) generated by Flasgger 
    "Try it out" options won't yield the expected Mocked Response Body since the Response Types are unsupported

-----------------------------------
Postman Collection
-----------------------------------

* Postman Collections and Environment are also committed and available in the repo in this directories:
  - wilfie-flask-app/api-docs/postman_collection.json
  - wilfie-flask-app/api-docs/postman_environment.json

  NOTE: Just import both the postman_collection.json and postman_environment.json on your Postman for usage

-----------------------------------
Pycharm Debug
-----------------------------------

configuration: python
script path: /app/bin/gunicorn
parameters: -b 0.0.0.0:8000 -t 200 -c python:src.config.gunicorn wilfie_flask_app.src.app:create_app()
working directory example: /Users/gavincliffe/Code/wilfie-flask-app
interpreter: remote
docker compose command and options: up web webpack worker sveltekit_app mcp_server
env tab -> enable env, add file: .env (command+shift+. to show hidden files on mac)

fastapi debug configuration:
remote interpreter
script path: /app/.venv/bin/uvicorn
script parameters: wilfie_fastapi_app.src.app:app --host 0.0.0.0 --port 8001 --reload --reload-dir /app/wilfie_fastapi_app
working directory example: /Users/gavincliffe/Code/wilfie-flask-app
docker compose command: up fastapi_app

Remote Interpreter
Docker-Compose
Server: Docker
Configuration files: ./docker-compose.yml; ./docker-compose.override.yml
Service: Web
Path mappings: <Project root>→/app

-----------------------------------
Ngrok
-----------------------------------

run terminal command:
ngrok http --region=au --hostname=wilfie.au.ngrok.io 7999

-----------------------------------
.ENV
-----------------------------------

SECRET_KEY= result from ./run flask secrets with test prefix

Ngrok :
    SERVER_NAME= your ngrok url

Pusher :
    PUSHER_APP_ID=
    PUSHER_KEY=
    PUSHER_SECRET=

AWS :
    AWS_ACCESS_KEY_ID=
    AWS_SECRET_ACCESS_KEY=
    AWS_SESSION_TOKEN=

Stripe :
    STRIPE_PUBLISHABLE_KEY=
    STRIPE_SECRET_KEY=

OpenAI :
    OPENAI_API_KEY

Sendinblue :
    SENDINBLUE_API_KEY

-----------------------------------
MCP Server
-----------------------------------

The project includes a standalone FastMCP server for running integrations and
workflows. It listens on `http://localhost:8003/mcp` and uses the Streamable
HTTP transport so responses can be streamed back to clients. Every request must
include `Authorization: Bearer <token>` where the token is a short lived JWT
signed with `SECRET_KEY`. Tokens are generated by the Flask application
whenever it calls the OpenAI Responses API and expire after
`MCP_TOKEN_EXPIRES_SECONDS` (defaults to 600 seconds). The server refuses to
start if `SECRET_KEY` is missing. Host and port can be configured with
`MCP_HOST` and `MCP_PORT`.
Use `FLASK_HOST` and `FLASK_PORT` to specify where the MCP server can
reach the Flask API.

-----------------------------------
Email Catcher
-----------------------------------

http://localhost:1080 to view emails sent in development

-----------------------------------
Wilfie API KEYs
-----------------------------------
create a test key for your local environment for AWS Lambdas to connect to:
./run flask redisinstance create-apikey --description "wilfie local api key"
add the key to .env

to check if your key already exists in redis run:
./run flask redisinstance get-apikeys


----------
ENCRYPTION
----------
To create a Fernet key for your environment:
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

use it in your .env file:
SECRET_ENCRYPTION_KEY=
