Add portable Windows build workflow

.github/workflows/build-windows-portable.yml

@@ -0,0 +1,51 @@
+name: build-windows-portable
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: backend/requirements.txt
+
+      - name: Build portable folder
+        shell: pwsh
+        run: ./build/windows/build_portable.ps1
+
+      - name: Smoke test executable
+        shell: pwsh
+        run: ./build/windows/smoke_test_portable.ps1
+
+      - name: Archive portable folder
+        shell: pwsh
+        run: |
+          if (Test-Path "dist/MesaFrame-portable.zip") {
+            Remove-Item "dist/MesaFrame-portable.zip" -Force
+          }
+          Compress-Archive -Path "dist/MesaFrame/*" -DestinationPath "dist/MesaFrame-portable.zip"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: MesaFrame-portable
+          path: |
+            dist/MesaFrame
+            dist/MesaFrame-portable.zip

.gitignore

@@ -8,6 +8,10 @@ __pycache__/
 # Node
 node_modules/
 frontend/dist/
+/dist/
+/build/*
+!/build/windows/
+!/build/windows/**
 
 # System
 .DS_Store
@@ -19,3 +23,6 @@ logs/**/*.jsonl
 backend/local_data/*.sqlite3
 backend/local_data/*.sqlite3-shm
 backend/local_data/*.sqlite3-wal
+
+# Local .dai model repository
+backend/app/core/pesquisa/modelos_dai/*.dai

README.md

@@ -57,6 +57,8 @@ Para apontar para outro backend:
 VITE_API_BASE=http://localhost:8000 npm run dev
 ```
 
+No build de producao servido pelo proprio backend, o frontend passa a usar a mesma origem (`/api`) por padrao.
+
 ## Repositório de modelos `.dai`
 
 Os modelos usados em **Pesquisa**, **Elaboração** (carregar modelo existente) e
@@ -129,3 +131,49 @@ Comportamento por ambiente:
 Variável opcional:
 
 - `APP_LOGS_MODE` (`auto`/`enabled`/`disabled`) para forçar o modo de logs.
+
+## Modo portátil Windows
+
+Planejamento atual da distribuicao:
+
+- o app continuara sendo desenvolvido normalmente no macOS;
+- a pasta portatil de Windows sera gerada em um ambiente Windows;
+- o artefato final sera uma pasta `MesaFrame/` gerada via `PyInstaller` em modo `onedir`;
+- a configuracao externa fica em `config/appsettings.json`;
+- o banco SQLite atual continua sendo reutilizado como esta;
+- os dados compartilhados podem ficar em pasta de rede e o runtime temporario fica local na maquina do usuario.
+
+Arquivos-base dessa estrategia:
+
+- `backend/portable_app.py`: entrada do modo portatil
+- `backend/app/portable_launcher.py`: sobe o backend local e abre o navegador
+- `backend/app/runtime_config.py`: aplica a configuracao externa
+- `build/windows/appsettings.example.json`: exemplo de configuracao
+- `build/windows/build_portable.ps1`: script de build para ambiente Windows
+- `build/windows/smoke_test_portable.ps1`: smoke test do executavel portatil
+- `build/windows/mesa_frame_portable.spec`: spec inicial do PyInstaller
+- `.github/workflows/build-windows-portable.yml`: workflow para gerar a pasta portatil em runner Windows
+
+Fluxo recorrente de release:
+
+1. desenvolver e validar normalmente no macOS
+2. fazer push da branch que sera empacotada
+3. disparar manualmente o workflow `.github/workflows/build-windows-portable.yml`
+4. baixar o artefato `MesaFrame-portable`
+5. copiar a pasta `MesaFrame/` para a rede
+6. ajustar `MesaFrame/config/appsettings.json` para os caminhos compartilhados da operacao
+7. no primeiro deploy, copiar manualmente a pasta de modelos `.dai` para o caminho configurado em `paths.models_dir`
+
+Estrutura esperada do artefato:
+
+- `MesaFrame/MesaFrame.exe`: executavel principal
+- `MesaFrame/_internal/`: runtime embutido do Python e dependencias
+- `MesaFrame/config/appsettings.example.json`: exemplo de configuracao externa
+- `MesaFrame/config/appsettings.json`: configuracao efetiva da instalacao
+- `MesaFrame/runtime/`: runtime temporario local usado nos testes automatizados
+
+Observacao sobre GitHub e dados:
+
+- o repositorio pode ficar somente com codigo e arquivos de suporte ao build
+- os modelos `.dai` devem ficar fora do Git e ser copiados manualmente para a pasta compartilhada da operacao
+- o `appsettings.json` publicado deve apontar `paths.models_dir` para essa pasta externa

backend/app/core/elaboracao/app.py

@@ -11,7 +11,9 @@ import pandas as pd
 import os
 import json
 
-_avaliadores_path = os.path.join(os.path.dirname(__file__), "avaliadores.json")
+from app.runtime_config import resolve_core_path
+
+_avaliadores_path = resolve_core_path("elaboracao", "avaliadores.json")
 with open(_avaliadores_path, encoding="utf-8") as _f:
     _avaliadores_raw = json.load(_f)
 _avaliadores_lista = _avaliadores_raw.get("avaliadores", [])

backend/app/core/elaboracao/formatadores.py

@@ -9,6 +9,7 @@ Sem dependência de Gradio.
 import os
 import numpy as np
 import pandas as pd
+from app.runtime_config import resolve_core_path
 
 
 # ============================================================
@@ -43,7 +44,7 @@ def arredondar_df(df, decimais=4):
 
 def carregar_css():
     """Carrega CSS externo."""
-    css_path = os.path.join(os.path.dirname(__file__), "styles.css")
+    css_path = resolve_core_path("elaboracao", "styles.css")
     try:
         with open(css_path, "r", encoding="utf-8") as f:
             return f.read()

backend/app/core/elaboracao/geocodificacao.py

@@ -11,14 +11,14 @@ import os
 import numpy as np
 import pandas as pd
 
+from app.runtime_config import resolve_core_path
 from .core import NOMES_LAT, NOMES_LON
 
 # ============================================================
 # CAMINHO DO SHAPEFILE
 # ============================================================
 
-_BASE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # raiz MESA/
-_SHAPEFILE = os.path.join(_BASE, "dados", "EixosLogradouros.shp")
+_SHAPEFILE = str(resolve_core_path("dados", "EixosLogradouros.shp"))
 
 # Cache em módulo — carregado uma vez por sessão
 _gdf_eixos = None

backend/app/core/map_layers.py

@@ -8,9 +8,9 @@ from typing import Any
 
 import folium
 from branca.element import Element
+from app.runtime_config import resolve_core_path
 
-_BASE_DIR = Path(__file__).resolve().parent
-_BAIRROS_SHP_PATH = _BASE_DIR / "dados" / "Bairros_LC12112_16.shp"
+_BAIRROS_SHP_PATH = resolve_core_path("dados", "Bairros_LC12112_16.shp")
 _TOOLTIP_FIELDS = ("NOME", "BAIRRO", "NME_BAI", "NOME_BAIRRO")
 _SIMPLIFY_TOLERANCE = 0.00005
 

backend/app/core/pesquisa/modelos_dai/MOD_A_CCOM_Z2_004D.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:ff221a8b0b6bec00a00f4c5ec0ff37429943328c943640fc98d3979074eb762c
-size 61298

backend/app/core/pesquisa/modelos_dai/MOD_A_CCOM_Z2_005.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:32bccd0c76e37878c83697700c3cd1cb1fa2cf8a25b714ef8a3609b031377487
-size 266364

backend/app/core/pesquisa/modelos_dai/MOD_A_CCOM_Z4_002N.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:92939746e3e2a2f1d455de0531c31b893c32415c22161478135321558a79ec8c
-size 78623

backend/app/core/pesquisa/modelos_dai/MOD_A_DEP_Z1_Z2_Z3_Z4_003B.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:77ff58a2844f5c54863eb0b06d8530e48db9af48d5f2255e3ca12d119d19d232
-size 105949

backend/app/core/pesquisa/modelos_dai/MOD_A_EDIF_Z1-Z2_001F.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:8053723e7c7e917e32709509bfb093ea718a65fec56ca095f0a99252cef69f75
-size 237021

backend/app/core/pesquisa/modelos_dai/MOD_A_EDIF_Z1_005D.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:df52dbf6e9902c69cf770c2149548b2c13b7f637a6a696b467a49601e5b8a50d
-size 62078

backend/app/core/pesquisa/modelos_dai/MOD_A_EDIF_Z1_Z2_001E.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:df8c18d84ecc169b41511e2743aca950680ebca0aadeee2b1978c2fd19716871
-size 63789

backend/app/core/pesquisa/modelos_dai/MOD_A_LOJA_Z1_003F.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:38580da29bd30d5c4cf5a20b008f3a852c6769f3915fa07ff46dbac4bf40be60
-size 124431

backend/app/core/pesquisa/modelos_dai/MOD_A_LOJA_Z1_004C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:b4bdcc13ef212a014deda190957a7c30beb8f2b42cd3c2518ee9dd0323e87930
-size 120063

backend/app/core/pesquisa/modelos_dai/MOD_A_LOJA_Z1_006B.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:1f6a14fe402b1ec5b3be1492492e01fb0b9050a03e049e22cc80ebbf7b4f88d2
-size 75212

backend/app/core/pesquisa/modelos_dai/MOD_A_LOJA_Z1_007C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:ce78dbb834e496a566e7d695a620ae96261ddc65f9fe397ab3ac0f65718f16e3
-size 82416

backend/app/core/pesquisa/modelos_dai/MOD_A_SALA_Z1_006B.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:4d241fad2e540fa24a79edc7ea798ddd22fe456af0ee7e59465c138c10265d6f
-size 122342

backend/app/core/pesquisa/modelos_dai/MOD_A_SALA_Z1_006C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:b7e81622c34e2333ba1a628d7f275a8fa71912f7da8b9720f37298ac285faf0b
-size 305073

backend/app/core/pesquisa/modelos_dai/MOD_A_SALA_Z1_Z3_001.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:d33b33df63a1d618ab2bcc26c5c111c698e8db9506d34622c0c1ed97fb18ad2c
-size 44681

backend/app/core/pesquisa/modelos_dai/MOD_V_AP_Z1_011D.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:49c49b0a46dd373ae7d16307516fa748ae4acc540462570f0c5e567928a29383
-size 5307946

backend/app/core/pesquisa/modelos_dai/MOD_V_AP_Z1_020B.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:f9f69d57ff5949afa8e43e6fe754b86b7d71098db740a70656db63ff003d46db
-size 1999539

backend/app/core/pesquisa/modelos_dai/MOD_V_AP_Z1_022.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:17944f8132fce958a7168d0efc73f4aa07575c16993a16022f89c2d7596c05d0
-size 1318594

backend/app/core/pesquisa/modelos_dai/MOD_V_EDIF_Z1_Z2_Z3_Z4_002E.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:7d64c816f183f6c18952eacf76fbce781d621d5b5ec5f4b51f40a85b0983e40d
-size 1577576

backend/app/core/pesquisa/modelos_dai/MOD_V_RCOND_Z4_004.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:70e655434ec5441708a1d0f108ae7b8af702cfb7577110db59846c7b4685879e
-size 836586

backend/app/core/pesquisa/modelos_dai/MOD_V_SALA_Z1_002E.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:a81098b6a7206d18f23e0676952fa60583283ea84293ea94ad0f84b1414a4210
-size 4622543

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_GENERICO_2016_2026_001.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:30565ca1281c1abe3f224f7309e40479fa20224fe68fade4ce146f804e728c09
-size 19220124

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z1_006L.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:47e009f401dd9644d030f90a0111ac4765bd1054a44027c2fb9f327fca7ad380
-size 1906640

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_008C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:ceaae08485539da6b97aded2086fa292a86c1f557cdd7875ba36f0b5f270d60c
-size 824103

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_013C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:46137a963d90e5697ef2e8c01ce5b56af6237ee426fc20662bbf99b14acb2743
-size 1481702

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_013F.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:cc522cf1e32ed0a3ff25157492accde2c0bc87e2013a2ea8ed3387317317de36
-size 2327452

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_015C_PORTO_SECO.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:d71651a7f845c893895bfd6b73c4209b597e1ba78b4c15c0924987f360c89108
-size 3635197

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_Z3_Z4_001H.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:749c833d7cd4190ea7cd0453410c63701746c8ac34b76444f0be55970700b185
-size 1731659

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_Z3_Z4_001i.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:fff0145b9990bb251401f85e5c1614fd84936801d6757482443987e1d880a099
-size 1969416

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_Z3_Z4_002A.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:762b80e17c476218ceb1f146e816c6b7a68f0011f35ec27f0535970602c5ea64
-size 1586112

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z2_Z3_Z4_002B.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:3468371b064f43da5b39d992bcccdb8d7c698e5f127e8040932e1bdf40ddcc1d
-size 1998609

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z4_003J.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:63059cf719829b1ab76852e6078b4d2808b6da734fa780e429bd852d000a24f6
-size 1559917

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z4_016E.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:ddbe47357238199b28515d42b6cc2730df5b9158b999431515947ae74cd73cdf
-size 5780373

backend/app/core/pesquisa/modelos_dai/MOD_V_TER_Z5_007C.dai

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:393b92b31396916b0cc500983649592f5ab0bdb6ed6d521b3abed2b9e5cf5235
-size 1372051

backend/app/core/pesquisa/modelos_dai/README.md

@@ -5,6 +5,11 @@ como `local` (`MODELOS_REPOSITORIO_PROVIDER=local`).
 
 Coloque nesta pasta os arquivos `.dai` que devem aparecer na aba **Pesquisa**.
 
+Quando o projeto for espelhado em um repositório GitHub para gerar o build
+portátil, os arquivos `.dai` nao devem ser versionados. Nesse fluxo, eles podem
+ser mantidos apenas localmente ou copiados manualmente para a pasta externa
+configurada em `paths.models_dir` no `config/appsettings.json`.
+
 ## Estrutura
 
 - `NOME_MODELO.dai`

backend/app/core/visualizacao/app.py

@@ -1,7 +1,8 @@
+from __future__ import annotations
+
 # ============================================================
 # IMPORTAÇÕES
 # ============================================================
-import gradio as gr
 import pandas as pd
 import numpy as np
 import folium
@@ -13,6 +14,23 @@ import traceback
 from datetime import datetime
 from html import escape
 
+from app.runtime_config import resolve_core_path
+
+try:
+    import gradio as gr
+except Exception:  # pragma: no cover - runtime portatil nao precisa da UI gradio
+    class _GradioPlaceholder:
+        class SelectData:
+            pass
+
+        @staticmethod
+        def update(*args, **kwargs):
+            raise RuntimeError("Gradio indisponivel neste runtime")
+
+        def __getattr__(self, name: str):
+            raise RuntimeError(f"Gradio indisponivel neste runtime: {name}")
+
+    gr = _GradioPlaceholder()
 
 # Importações para gráficos (trazidas de graficos.py)
 from scipy import stats
@@ -50,7 +68,7 @@ COR_LINHA = '#dc3545'  # Vermelho para linhas de referência
 # ============================================================
 def carregar_css():
     """Carrega o arquivo CSS externo."""
-    css_path = os.path.join(os.path.dirname(__file__), "styles.css")
+    css_path = resolve_core_path("visualizacao", "styles.css")
     try:
         with open(css_path, "r", encoding="utf-8") as f:
             return f.read()

backend/app/main.py

@@ -8,9 +8,12 @@ from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 
 from app.api import auth, elaboracao, health, logs, pesquisa, repositorio, session, trabalhos_tecnicos, visualizacao
+from app.runtime_config import apply_runtime_config, resolve_frontend_dist_dir
 from app.services import auth_service
 
 
+apply_runtime_config()
+
 app = FastAPI(
     title="MESA Frame API",
     version="1.0.0",
@@ -58,7 +61,7 @@ app.include_router(logs.router)
 
 
 def _mount_frontend_if_exists() -> None:
-    frontend_dist = Path(__file__).resolve().parents[2] / "frontend" / "dist"
+    frontend_dist = resolve_frontend_dist_dir()
     index_file = frontend_dist / "index.html"
     if not index_file.exists():
         return

backend/app/portable_launcher.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import socket
+import threading
+import time
+import urllib.request
+import webbrowser
+
+import uvicorn
+
+from app.runtime_config import RuntimeSettings, apply_runtime_config
+
+
+def _first_available_port(host: str, preferred_port: int, max_attempts: int = 20) -> int:
+    for offset in range(max_attempts):
+        port = preferred_port + offset
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+            except OSError:
+                continue
+        return port
+    raise RuntimeError(f"Nao foi possivel reservar uma porta local a partir de {preferred_port}")
+
+
+def _wait_for_server_and_open_browser(url: str, timeout_s: float = 45.0) -> None:
+    health_url = f"{url.rstrip('/')}/api/health"
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        try:
+            with urllib.request.urlopen(health_url, timeout=1.5) as response:
+                if response.status == 200:
+                    webbrowser.open(url)
+                    return
+        except Exception:
+            time.sleep(0.5)
+
+
+def _build_server(settings: RuntimeSettings) -> tuple[uvicorn.Server, str]:
+    port = _first_available_port(settings.host, settings.port)
+    url = f"http://{settings.host}:{port}"
+
+    from app.main import app
+
+    config = uvicorn.Config(
+        app=app,
+        host=settings.host,
+        port=port,
+        reload=False,
+        log_level="info",
+    )
+    return uvicorn.Server(config), url
+
+
+def main() -> int:
+    settings = apply_runtime_config()
+    server, url = _build_server(settings)
+
+    print(f"[mesa] iniciando servidor local em {url}")
+    if settings.config_path is not None:
+        print(f"[mesa] configuracao carregada de {settings.config_path}")
+    print(f"[mesa] runtime local em {settings.runtime_dir}")
+
+    if settings.open_browser:
+        opener = threading.Thread(target=_wait_for_server_and_open_browser, args=(url,), daemon=True)
+        opener.start()
+
+    try:
+        server.run()
+    except KeyboardInterrupt:
+        print("[mesa] encerrando aplicativo")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

backend/app/runtime_config.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+_APPLIED_SETTINGS: "RuntimeSettings | None" = None
+
+
+@dataclass(frozen=True)
+class RuntimeSettings:
+    config_path: Path | None
+    app_root: Path
+    runtime_dir: Path
+    host: str
+    port: int
+    open_browser: bool
+
+
+def resolve_app_root() -> Path:
+    if getattr(sys, "frozen", False):
+        return Path(sys.executable).resolve().parent
+    return Path(__file__).resolve().parents[2]
+
+
+def resolve_bundle_root() -> Path:
+    meipass = getattr(sys, "_MEIPASS", None)
+    if meipass:
+        return Path(str(meipass)).resolve()
+    if getattr(sys, "frozen", False):
+        return Path(sys.executable).resolve().parent
+    return resolve_app_root()
+
+
+def resolve_frontend_dist_dir() -> Path:
+    base = resolve_bundle_root() if getattr(sys, "frozen", False) else resolve_app_root()
+    return base / "frontend" / "dist"
+
+
+def resolve_core_path(*parts: str) -> Path:
+    if getattr(sys, "frozen", False):
+        return resolve_bundle_root().joinpath("app", "core", *parts)
+    return resolve_app_root().joinpath("backend", "app", "core", *parts)
+
+
+def resolve_local_data_path(*parts: str) -> Path:
+    if getattr(sys, "frozen", False):
+        return resolve_bundle_root().joinpath("local_data", *parts)
+    return resolve_app_root().joinpath("backend", "local_data", *parts)
+
+
+def _default_runtime_dir() -> Path:
+    app_name = "MesaFrame"
+    if sys.platform == "win32":
+        base = Path(str(os.getenv("LOCALAPPDATA") or Path.home() / "AppData" / "Local"))
+        return base / app_name
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / app_name
+    return Path(str(os.getenv("XDG_STATE_HOME") or (Path.home() / ".local" / "state"))) / app_name
+
+
+def _expand_path(value: Any, base_dir: Path | None = None) -> Path | None:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    expanded = os.path.expandvars(text)
+    path = Path(expanded).expanduser()
+    if not path.is_absolute():
+        anchor = base_dir or resolve_app_root()
+        path = anchor / path
+    return path.resolve()
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if value is None:
+        return default
+    text = str(value).strip().lower()
+    if text in {"1", "true", "yes", "y", "on", "sim"}:
+        return True
+    if text in {"0", "false", "no", "n", "off", "nao", "não"}:
+        return False
+    return default
+
+
+def _as_int(value: Any, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        parsed = int(str(value).strip())
+    except Exception:
+        return default
+    return parsed if parsed > 0 else default
+
+
+def _read_config_file(config_path: Path | None) -> dict[str, Any]:
+    if config_path is None or not config_path.exists():
+        return {}
+    try:
+        payload = json.loads(config_path.read_text(encoding="utf-8"))
+    except Exception as exc:  # pragma: no cover - surfaced to caller in packaged runtime
+        raise RuntimeError(f"Falha ao ler arquivo de configuracao '{config_path}': {exc}") from exc
+    if not isinstance(payload, dict):
+        raise RuntimeError(f"Arquivo de configuracao invalido: '{config_path}'")
+    return payload
+
+
+def _default_config_path(app_root: Path) -> Path:
+    return app_root / "config" / "appsettings.json"
+
+
+def _set_env_if_value(key: str, value: Any) -> None:
+    text = str(value or "").strip()
+    if text:
+        os.environ[key] = text
+
+
+def apply_runtime_config(config_path: str | Path | None = None) -> RuntimeSettings:
+    global _APPLIED_SETTINGS
+    if _APPLIED_SETTINGS is not None:
+        return _APPLIED_SETTINGS
+
+    app_root = resolve_app_root()
+    config_source = config_path or os.getenv("MESA_APP_CONFIG") or _default_config_path(app_root)
+    config_file = _expand_path(config_source)
+    payload = _read_config_file(config_file)
+    config_base_dir = config_file.parent if config_file is not None else app_root
+
+    server_cfg = payload.get("server") if isinstance(payload.get("server"), dict) else {}
+    paths_cfg = payload.get("paths") if isinstance(payload.get("paths"), dict) else {}
+    env_cfg = payload.get("env") if isinstance(payload.get("env"), dict) else {}
+
+    runtime_dir = _expand_path(paths_cfg.get("runtime_dir"), base_dir=config_base_dir) or _default_runtime_dir()
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    (runtime_dir / "sessions").mkdir(parents=True, exist_ok=True)
+    (runtime_dir / "logs").mkdir(parents=True, exist_ok=True)
+
+    os.environ.setdefault("MESA_RUNTIME_DIR", str(runtime_dir))
+
+    models_dir = _expand_path(paths_cfg.get("models_dir"), base_dir=config_base_dir)
+    if models_dir is not None:
+        os.environ["MODELOS_REPOSITORIO_PROVIDER"] = "local"
+        os.environ["MODELOS_REPOSITORIO_LOCAL_DIR"] = str(models_dir)
+
+    trabalhos_db = _expand_path(paths_cfg.get("trabalhos_tecnicos_db"), base_dir=config_base_dir)
+    if trabalhos_db is not None:
+        os.environ["TRABALHOS_TECNICOS_PROVIDER"] = "local"
+        os.environ["TRABALHOS_TECNICOS_DB_LOCAL_PATH"] = str(trabalhos_db)
+
+    users_file = _expand_path(paths_cfg.get("users_file"), base_dir=config_base_dir)
+    if users_file is not None:
+        os.environ["APP_USERS_FILE"] = str(users_file)
+
+    logs_mode = env_cfg.get("APP_LOGS_MODE")
+    if logs_mode is None and getattr(sys, "frozen", False):
+        logs_mode = "disabled"
+    _set_env_if_value("APP_LOGS_MODE", logs_mode)
+
+    for key, value in env_cfg.items():
+        if key == "APP_LOGS_MODE":
+            continue
+        _set_env_if_value(key, value)
+
+    settings = RuntimeSettings(
+        config_path=config_file if config_file and config_file.exists() else None,
+        app_root=app_root,
+        runtime_dir=runtime_dir,
+        host=str(server_cfg.get("host") or "127.0.0.1").strip() or "127.0.0.1",
+        port=_as_int(server_cfg.get("port"), 8000),
+        open_browser=_as_bool(server_cfg.get("open_browser"), True),
+    )
+    _APPLIED_SETTINGS = settings
+    return settings

backend/app/services/auth_service.py

@@ -10,7 +10,10 @@ from typing import Any
 
 from fastapi import HTTPException, Request
 
-DEFAULT_USERS_FILE = Path(__file__).resolve().parent.parent / "core" / "auth" / "usuarios.json"
+from app.runtime_config import resolve_core_path
+
+
+DEFAULT_USERS_FILE = resolve_core_path("auth", "usuarios.json")
 
 _USERS_LOCK = Lock()
 _SESSIONS_LOCK = Lock()

backend/app/services/elaboracao_service.py

@@ -54,12 +54,13 @@ from app.core.elaboracao.formatadores import (
     formatar_outliers_anteriores_html,
 )
 from app.models.session import SessionState
+from app.runtime_config import resolve_core_path
 from app.services import model_repository
 from app.services.equacao_service import build_equacoes_payload, exportar_planilha_equacao
 from app.services.knn_avaliacao_service import estimar_valor_knn_avaliacao
 from app.services.serializers import dataframe_to_payload, figure_to_payload, sanitize_value
 
-_AVALIADORES_PATH = Path(__file__).resolve().parent.parent / "core" / "elaboracao" / "avaliadores.json"
+_AVALIADORES_PATH = resolve_core_path("elaboracao", "avaliadores.json")
 _AVALIADORES_CACHE: list[dict[str, Any]] | None = None
 LIMIAR_DISPERSAO_PNG = 1500
 LOGGER = logging.getLogger(__name__)

backend/app/services/model_repository.py

@@ -10,6 +10,7 @@ from threading import Lock
 from typing import Any
 
 from fastapi import HTTPException
+from app.runtime_config import resolve_core_path
 
 try:
     from huggingface_hub import CommitOperationAdd, CommitOperationDelete, HfApi, snapshot_download
@@ -20,7 +21,7 @@ except Exception:  # pragma: no cover - dependência opcional em tempo de import
     snapshot_download = None  # type: ignore[assignment]
 
 
-DEFAULT_LOCAL_MODELOS_DIR = Path(__file__).resolve().parent.parent / "core" / "pesquisa" / "modelos_dai"
+DEFAULT_LOCAL_MODELOS_DIR = resolve_core_path("pesquisa", "modelos_dai")
 DEFAULT_HF_REPO_ID = "gui-sparim/repositorio_mesa"
 DEFAULT_HF_REVISION = "main"
 DEFAULT_HF_SUBDIR = "modelos_dai"

backend/app/services/session_store.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import shutil
 import tempfile
 import uuid
@@ -16,7 +17,12 @@ class SessionStore:
 
     def create(self) -> SessionState:
         session_id = uuid.uuid4().hex
-        workdir = Path(tempfile.mkdtemp(prefix=f"mesa_{session_id[:8]}_"))
+        runtime_root = str(os.getenv("MESA_RUNTIME_DIR") or "").strip()
+        temp_root = None
+        if runtime_root:
+            temp_root = Path(runtime_root).expanduser().resolve() / "sessions"
+            temp_root.mkdir(parents=True, exist_ok=True)
+        workdir = Path(tempfile.mkdtemp(prefix=f"mesa_{session_id[:8]}_", dir=str(temp_root) if temp_root else None))
         state = SessionState(session_id=session_id, workdir=workdir)
         self._sessions[session_id] = state
         return state

backend/app/services/trabalhos_tecnicos_repository.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from fastapi import HTTPException
+from app.runtime_config import resolve_local_data_path
 
 try:
     from huggingface_hub import HfApi, hf_hub_download
@@ -58,7 +59,7 @@ def _local_db_path() -> Path:
     raw = str(os.getenv("TRABALHOS_TECNICOS_DB_LOCAL_PATH") or "").strip()
     if raw:
         return Path(raw).expanduser().resolve()
-    return (Path(__file__).resolve().parents[2] / "local_data" / DEFAULT_LOCAL_DB_FILE).resolve()
+    return resolve_local_data_path(DEFAULT_LOCAL_DB_FILE).resolve()
 
 
 def _hf_repo_id() -> str: