deployment, linting and infra configuration

docs/DEPLOYMENT_PLAN.md

@@ -7,6 +7,7 @@ This plan outlines the strategy to host both the **AI Tax Agent application** an
 ## Current State Analysis
 
 ### Remote Server (`141.136.35.199`)
+
 - **Location**: `/opt/compose/`
 - **Existing Services**:
   - Traefik v3.5.1 (reverse proxy with GoDaddy DNS challenge)
@@ -25,6 +26,7 @@ This plan outlines the strategy to host both the **AI Tax Agent application** an
   - `portainer.harkon.co.uk`
 
 ### Local Repository (`infra/compose/`)
+
 - **Compose Files**:
   - `docker-compose.local.yml` - Full stack for local development
   - `docker-compose.backend.yml` - Backend services (appears to be production-ready)
@@ -39,25 +41,30 @@ This plan outlines the strategy to host both the **AI Tax Agent application** an
 ## Challenges & Conflicts
 
 ### 1. **Duplicate Services**
+
 - Both environments have Traefik and Authentik
 - Need to decide: shared vs. isolated
 
 ### 2. **Network Naming**
+
 - Remote: `frontend`, `backend`
 - Local: `ai-tax-agent-frontend`, `ai-tax-agent-backend`
 - Production needs: Consistent naming
 
 ### 3. **Domain Management**
+
 - Remote: `*.harkon.co.uk` (public)
 - Local: `*.local.lan` (development)
 - Production: Need subdomains like `app.harkon.co.uk`, `api.harkon.co.uk`
 
 ### 4. **SSL Certificates**
+
 - Remote: GoDaddy DNS challenge (production)
 - Local: Self-signed certificates
 - Production: Must use GoDaddy DNS challenge
 
 ### 5. **Resource Isolation**
+
 - Company services need to remain stable
 - Application services need independent deployment/rollback
 
@@ -66,6 +73,7 @@ This plan outlines the strategy to host both the **AI Tax Agent application** an
 We will deploy the company services and the AI Tax Agent as two fully isolated stacks, each with its own Traefik and Authentik. This maximizes blast-radius isolation and avoids naming and DNS conflicts across environments.
 
 Key implications:
+
 - Separate external networks and DNS namespaces per stack
 - Duplicate edge (Traefik) and IdP (Authentik), independent upgrades and rollbacks
 - Slightly higher resource usage in exchange for strong isolation
@@ -139,6 +147,7 @@ Key implications:
 ### Domain Mapping
 
 **Company Services** (existing):
+
 - `traefik.harkon.co.uk` - Traefik dashboard
 - `auth.harkon.co.uk` - Authentik SSO
 - `gitea.harkon.co.uk` - Git hosting
@@ -146,6 +155,7 @@ Key implications:
 - `portainer.harkon.co.uk` - Docker management
 
 **Application Services** (app stack):
+
 - `review.<domain>` - Review UI
 - `api.<domain>` - API Gateway (microservices via Traefik)
 - `vault.<domain>` - Vault UI (admin only)
@@ -159,12 +169,14 @@ Key implications:
 ### Authentication Strategy
 
 **Authentik Configuration**:
+
 1. **Company Group** - Access to Gitea, Nextcloud, Portainer
 2. **App Admin Group** - Full access to all app services
 3. **App User Group** - Access to Review UI and API
 4. **App Reviewer Group** - Access to Review UI only
 
 **Middleware Configuration**:
+
 - `authentik-forwardauth` - Standard auth for all services
 - `admin-auth` - Requires admin group (Vault, MinIO, Neo4j, etc.)
 - `reviewer-auth` - Requires reviewer or higher
@@ -182,6 +194,7 @@ Key implications:
 ### Development Environment
 
 **Keep Existing Setup**:
+
 - Use `docker-compose.local.yml` as-is
 - Domain: `*.local.lan`
 - Self-signed certificates
@@ -189,6 +202,7 @@ Key implications:
 - Full stack runs locally
 
 **Benefits**:
+
 - No dependency on remote server
 - Fast iteration
 - Complete isolation
@@ -217,19 +231,22 @@ make deploy-production  # Deploy to remote server
 ### Phase 1: Preparation (Week 1)
 
 1. **Backup Current State**
+
    ```bash
    ssh deploy@141.136.35.199
-   cd /opt/compose
+   cd /opt
    tar -czf ~/backup-$(date +%Y%m%d).tar.gz .
    ```
 
 2. **Create Production Environment File**
-   - Copy `infra/compose/env.example` to `infra/compose/.env.production`
+
+   - Copy `infra/environments/production/.env.example` to `infra/environments/production/.env`
    - Update all secrets and passwords
    - Set `DOMAIN=harkon.co.uk`
    - Configure GoDaddy API credentials
 
 3. **Update Traefik Configuration**
+
    - Merge local Traefik config with remote
    - Add application routes
    - Configure Authentik ForwardAuth
@@ -242,13 +259,15 @@ make deploy-production  # Deploy to remote server
 ### Phase 2: Infrastructure Deployment (Week 2)
 
 1. **Deploy Application Infrastructure**
+
    ```bash
    # On remote server
-   cd /opt/compose/ai-tax-agent
+   cd /opt/ai-tax-agent
    docker compose -f infrastructure.yaml up -d
    ```
 
 2. **Initialize Services**
+
    - Vault: Unseal and configure
    - Postgres: Run migrations
    - Neo4j: Install plugins
@@ -262,11 +281,13 @@ make deploy-production  # Deploy to remote server
 ### Phase 3: Application Deployment (Week 3)
 
 1. **Deploy Microservices**
+
    ```bash
    docker compose -f services.yaml up -d
    ```
 
 2. **Deploy Monitoring**
+
    ```bash
    docker compose -f monitoring.yaml up -d
    ```