feat: initial FlowBoard implementation

Signed-off-by: Damian Skrzyński <polprog.tech@gmail.com>

Author: polprog-dev

.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" httpx
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest --cov=flowboard --cov-report=xml -v --junitxml=test-results.xml
+
+      - name: i18n coverage check
+        run: python -c "
+          import json, sys;
+          en = set(json.load(open('src/flowboard/i18n/en.json')).keys());
+          pl = set(json.load(open('src/flowboard/i18n/pl.json')).keys());
+          missing = en - pl;
+          [print(f'Missing in pl.json: {k}') for k in sorted(missing)];
+          sys.exit(1) if missing else print('i18n: all keys present')
+          "
+
+      - name: Generate demo dashboard
+        run: flowboard demo --output output/demo.html
+
+      - name: Verify demo output exists
+        run: test -f output/demo.html
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: test-results.xml
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t flowboard:latest .
+
+      - name: Smoke test container
+        run: |
+          docker run -d --name fb-test -p 8084:8084 flowboard:latest serve --host 0.0.0.0 --port 8084
+          sleep 5
+          curl -sf http://localhost:8084/health/live || exit 1
+          docker stop fb-test

.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.env
+*.env
+config.json
+!examples/config.example.json
+output/
+*.html
+!src/flowboard/presentation/html/templates/**/*.html
+.venv/
+venv/
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [1.0.0] - 2026-03-28
+
+### Added
+
+- Jira-based roadmap, delivery, and workload intelligence dashboard
+- Board snapshot analytics with dependency heatmaps
+- Multi-locale i18n support (EN, PL)
+- HTML report generation with Jinja2 templates
+- CLI interface via Typer
+- FastAPI-based web server with uvicorn
+- JSON Schema configuration validation
+- Docker and docker-compose deployment support

CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to FlowBoard
+
+Thank you for your interest in improving FlowBoard! This document provides guidelines for contributing.
+
+## Development Setup
+
+```bash
+git clone https://github.com/POLPROG-TECH/FlowBoard.git
+cd FlowBoard
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Code Standards
+
+- **Python 3.12+** with full type hints on all public APIs
+- **Ruff** for linting and formatting: `ruff check src/ tests/`
+- **mypy** for type checking: `mypy src/flowboard/`
+- **pytest** for testing: `pytest`
+
+## Architecture
+
+FlowBoard follows a clean layered architecture. See `docs/architecture.md` for details.
+
+```
+src/flowboard/
+├── cli/              # Typer CLI (generate, validate, verify, demo, version)
+├── application/      # Orchestration pipeline, services
+├── domain/           # Models, analytics, risk, workload, overlap, dependencies,
+│                     #   timeline, scrum, simulation, pi
+├── infrastructure/   # Jira client/connector/normalizer, config loader/validator
+├── i18n/             # Translator engine, en.json, pl.json (927 keys)
+├── presentation/     # HTML renderer, Jinja2 templates, components, charts, export
+└── shared/           # Types, enums, utilities
+```
+
+Key rules:
+- Domain layer has **zero** infrastructure imports
+- Presentation layer depends on domain, never on Jira client directly
+- Config is loaded once and passed down — no global singletons
+- All Jira API access goes through `infrastructure/jira/`
+
+## Making Changes
+
+1. Create a feature branch from `main`
+2. Write or update tests for your changes
+3. Ensure all tests pass: `pytest`
+4. Ensure linting passes: `ruff check src/ tests/`
+5. Submit a pull request with a clear description
+
+## Test Guidelines
+
+- Use **GIVEN / WHEN / THEN** style for behavior tests
+- Mock Jira API calls — never hit real Jira in tests
+- Focus on analytics correctness and edge cases
+- Keep tests fast and isolated
+
+## Commit Messages
+
+Use clear, descriptive commit messages:
+```
+feat: add burndown chart to sprint health view
+fix: correct story point aggregation for sub-tasks
+docs: update configuration guide for custom fields
+```
+
+## Internationalization (i18n)
+
+FlowBoard supports multiple languages. Currently supported locales: **English (en)** and **Polish (pl)**.
+
+### Selecting a Language
+
+Set the locale in your config file:
+```json
+{ "locale": "pl" }
+```
+
+Or via CLI flag:
+```bash
+flowboard generate --config config.json --locale pl
+```
+
+Or via environment variable:
+```bash
+export FLOWBOARD_LOCALE=pl
+```
+
+**Precedence:** CLI flag > environment variable > config file > default (`en`).
+
+### Translation Files
+
+Translation files are JSON files in `src/flowboard/i18n/`:
+- `en.json` — English (reference/source)
+- `pl.json` — Polish
+
+### Adding or Updating Translations
+
+1. Add the new key to **both** `en.json` and `pl.json`.
+2. Use flat dot-notation keys (e.g. `"section.overview": "Overview"`).
+3. For interpolation, use `{variable}` placeholders: `"error.auth_failed": "Auth failed ({code})"`.
+4. For plurals, provide separate keys: `plural.day.one`, `plural.day.few`, `plural.day.many`, `plural.day.other`.
+5. Run `pytest tests/test_i18n.py` to verify key parity and placeholder consistency.
+
+### Using Translations in Code
+
+```python
+from flowboard.i18n.translator import Translator
+
+t = Translator("pl")
+t("tab.overview")           # "📋 Przegląd"
+t("cli.error", error="x")  # "Błąd: x"
+t.plural(3, "plural.day.one", "plural.day.few", "plural.day.many")  # "3 dni"
+t.format_date_short(date)   # "18 mar"
+t.format_number(1234.5)     # "1 234,5"
+```
+
+### Adding a New Language
+
+1. Copy `en.json` to `<code>.json` (e.g. `de.json`).
+2. Translate all values.
+3. Update `_meta.locale` to the new code.
+4. Add the locale code to the `"locale"` enum in `config.schema.json`.
+5. Add the locale code to the Pydantic config model's locale field.
+6. Add plural rules in `translator.py` if the language has complex pluralization.
+7. Run `pytest tests/test_i18n.py` to verify.
+
+## Questions?
+
+Open an issue or reach out to the FlowBoard team internally.

Dockerfile

@@ -0,0 +1,39 @@
+FROM python:3.13-slim AS builder
+
+WORKDIR /build
+COPY pyproject.toml README.md ./
+COPY src/ src/
+
+RUN pip install --no-cache-dir --prefix=/install .
+
+# ── Runtime stage ──────────────────────────────────────────────────
+FROM python:3.13-slim
+
+LABEL maintainer="FlowBoard Team"
+LABEL org.opencontainers.image.title="FlowBoard"
+LABEL org.opencontainers.image.description="Jira-Based Delivery & Workload Intelligence Dashboard"
+
+RUN groupadd -r flowboard && useradd -r -g flowboard -d /app flowboard
+
+COPY --from=builder /install /usr/local
+COPY src/ /app/src/
+COPY examples/ /app/examples/
+COPY config.schema.json /app/
+
+WORKDIR /app
+RUN mkdir -p /app/output && chown -R flowboard:flowboard /app
+
+USER flowboard
+
+ENV PYTHONPATH=/app/src \
+    PYTHONUNBUFFERED=1 \
+    FLOWBOARD_LOG_FORMAT=json \
+    PORT=8084
+
+EXPOSE 8084
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD python -c "import os,urllib.request; urllib.request.urlopen(f'http://localhost:{os.environ.get(\"PORT\",\"8084\")}/health/live')" || exit 1
+
+ENTRYPOINT ["flowboard"]
+CMD ["serve", "--host", "0.0.0.0", "--port", "8084"]