TeamBeacon is a local-first engineering intelligence app that sits on top of existing delivery data sources and helps Engineering Managers operate with clearer signals, lower cognitive load, and better delivery outcomes.

• Local-first workflow on the manager's machine.
• Non-destructive integration model (does not modify upstream source data).
• Metadata-driven insight layer (Group/Type/Epic configuration).
• AI-powered insights with pluggable provider support (OCI, Ollama, OpenAI).

• Settings: source connectivity checks, sync controls, metadata configuration, and AI Model Connection status (provider + model).
• Initiative Insights: progress matrix, filters, and RAG visibility.
• Team Insights: sprint trend window controls (1/2/3/4/6/8/10/12), completed story points, and cycle-time trend metrics.
• Sprint Insights: state breakdown, work mix, scope-change and blocker visibility.
• Team Dashboard: AI-generated summary, wins/risks, initiative progress, and work-mix visibility for leadership updates.

For product messaging, capability narrative, and value framing, see:

• TeamBeacon Communication One-Pager

Settings Overview	Initiative Insights
Sprint Insights	Team Dashboard

TeamBeacon/                  # Repository root
  app/                       # Oracle JET frontend + Tauri desktop shell
  services/                  # Runtime services
    api/                     # Local API endpoints and orchestration
  packages/                  # Shared Python packages
    connectors/              # Source connector configs and clients
  docs/                      # Product/architecture/design/ops/communication documentation
    communication/           # Communication one-pager and redacted screenshots
    architecture/            # Architecture reference docs
    design/                  # UI/UX mockups and design notes
    plans/                   # Delivery and implementation plans
    ops/                     # Operational runbooks
  tests/                     # Backend unit/integration test suites

• git for cloning and collaboration.
• docker for the fastest TeamBeacon setup.
• python3 (3.11+ recommended) for API/runtime and backend tests.
• node and npm (Node 22 recommended, aligned with CI) for frontend build/test.
• sqlite3 CLI for local DB schema setup and ad-hoc DB checks.
• Rust toolchain (rustup, cargo, rustc) for Tauri desktop commands.
• Tauri CLI via cargo: cargo install tauri-cli
• OCI Python SDK (required only when INTELLIGENCE_PROVIDER=oci): python3 -m pip install oci
• Platform prerequisites for Tauri desktop builds (macOS): Xcode Command Line Tools (xcode-select --install)

1. Clone and enter the repository:

git clone https://github.com/git-mhaque/TeamBeacon && cd TeamBeacon

2. Configure environment variables:

cp config/.env.example config/.env

Configuration details are documented in config/README.md.

3. Start TeamBeacon:

docker compose up -d --build

# Optional non-default port:
TEAMBEACON_HOST_PORT=19000 docker compose up -d --build

4. Access TeamBeacon:

• http://localhost:18000

1. Clone and enter the repository:

git clone https://github.com/git-mhaque/TeamBeacon && cd TeamBeacon

2. Configure environment variables:

cp config/.env.example config/.env

Configuration details are documented in config/README.md.

3. Apply local database schema (mandatory before first local run):

test -f data/teambeacon.db || sqlite3 data/teambeacon.db < services/api/db/migrations/0001_initial.sql

4. Start frontend + local API:

cd app
npm install
npm run dev

• Frontend: http://localhost:5174
• API: http://localhost:8000
• API Swagger UI: http://localhost:8000/docs
• API OpenAPI schema: http://localhost:8000/openapi.json

5. Run backend tests:

python3 -m unittest discover -s tests/unit -p "test_*.py" -v
python3 -m unittest discover -s tests/integration/api -p "test_*.py" -v

6. Run frontend checks:

cd app
npm run build
npm run test:coverage

From app/:

npm run desktop:dev
npm run desktop:build

• GitHub Actions workflow: .github/workflows/ci.yml
• Checks:
  • Backend unit tests
  • Backend API integration tests
  • Frontend (OJET) build + coverage tests: cd app && npm ci && npm run build && npm run test:coverage
  • Docker image build on PRs; build + publish to GHCR on main

• TeamBeacon Communication One-Pager: product narrative, value framing, and screenshots
• AGENTS.md: contributor conventions and repository map
• LICENSE: Apache License 2.0 terms for this repository
• config/README.md: required and optional environment variables
• services/api/README.md: local API endpoints and Swagger/OpenAPI docs
• SPEC.md: product requirements and scope boundaries
• docs/architecture/ARCHITECTURE.md: technical architecture baseline
• docs/plans/PLAN.md: phased delivery roadmap
• docs/design/README.md: design artifact overview
• docs/ops/OCI_GENAI_CONNECTIVITY_SMOKE_TEST.md: OCI-specific smoke test (use when INTELLIGENCE_PROVIDER=oci)