Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Current architecture

The deployed web frontend calls the flow bridge and query engine APIs. The flow bridge receives GitHub App webhooks, calls the query engine after refresh, and both backend services use Temporal and PostgreSQL.

```mermaid
architecture-beta
group consumers[Consumers and entry points]
group backend[Backend services]
group platform[Platform and infrastructure]
group external[External services]

service browser(internet)[Browser] in consumers
service frontend(server)[Web frontend] in consumers
service flow_bridge(server)[Flow bridge API] in backend
service query_engine(server)[Query engine API] in backend
service temporal(server)[Temporal workflow service] in platform
service postgresql(database)[PostgreSQL] in platform
service github(internet)[GitHub] in external

browser:R --> L:frontend
frontend:R --> L:flow_bridge
frontend:R --> L:query_engine
github:R --> L:flow_bridge
flow_bridge:R --> L:query_engine
flow_bridge:R --> L:temporal
flow_bridge:R --> L:postgresql
query_engine:R --> L:temporal
query_engine:R --> L:postgresql
temporal:R --> L:postgresql

align column flow_bridge query_engine
```
10 changes: 7 additions & 3 deletions unoplat-code-confluence-cli/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:BEGIN -->
<CRITICAL_INSTRUCTION>

> Generated from branch `dev` at commit `3bbc2c8ae5f6fc7e94628c3b07a936ca5bdbcd02` (2026-06-09). Content may become stale as new commits land.
> Generated from branch `dev` at commit `5ecdba39d57f50c5188a8e32b9dd4f52d01611fe` (2026-07-18). Content may become stale as new commits land.

</CRITICAL_INSTRUCTION>

Expand All @@ -13,7 +13,7 @@
- `uv build` — `pyproject.toml`

### Dev
- `uv run unoplat` — `pyproject.toml` (project script entry point)
- `uv run ucc` — `pyproject.toml` (project script entry point)

### Test
- Not detected
Expand All @@ -29,7 +29,8 @@ See [`dependencies_overview.md`](./dependencies_overview.md) for the full depend

## Business Domain
### Description
Unoplat Code Confluence CLI manages the local Code Confluence Docker Compose stack: it fetches and pins GitHub releases, installs or repairs release assets, starts the Flow Bridge/query engine/frontend services, and opens browser setup pages for repository token and model-provider configuration.

Unoplat Code Confluence CLI manages a local Docker Compose deployment for repository-aware AI code assistance, including Flow Bridge, a query engine, and a frontend. It registers and refreshes Git repositories, verifies repository and model-provider credentials, tracks GitHub release manifests and installed state, and initiates AGENTS.md-generation workflows that raise pull requests.

### References

Expand All @@ -38,4 +39,7 @@ See [`business_domain_references.md`](./business_domain_references.md) for the s
## App Interfaces
See [`app_interfaces.md`](./app_interfaces.md) for the canonical interface and endpoint reference.

## Architecture
See [`architecture.md`](./architecture.md) for the canonical system architecture diagram.
Comment on lines +42 to +43

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the nested links to the root architecture document.

Each nested AGENTS.md file currently resolves ./architecture.md within its own directory instead of the repository root.

  • unoplat-code-confluence-cli/AGENTS.md#L42-L43: change the link to ../architecture.md.
  • unoplat-code-confluence-commons/AGENTS.md#L66-L67: change the link to ../architecture.md.
  • unoplat-code-confluence-docs/AGENTS.md#L72-L74: change the link to ../architecture.md.
📍 Affects 3 files
  • unoplat-code-confluence-cli/AGENTS.md#L42-L43 (this comment)
  • unoplat-code-confluence-commons/AGENTS.md#L66-L67
  • unoplat-code-confluence-docs/AGENTS.md#L72-L74
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@unoplat-code-confluence-cli/AGENTS.md` around lines 42 - 43, Update the
Architecture links in unoplat-code-confluence-cli/AGENTS.md lines 42-43,
unoplat-code-confluence-commons/AGENTS.md lines 66-67, and
unoplat-code-confluence-docs/AGENTS.md lines 72-74 from ./architecture.md to
../architecture.md so each points to the repository-root document.


<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:END -->
53 changes: 38 additions & 15 deletions unoplat-code-confluence-cli/business_domain_references.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,43 @@
# Business Domain References

## Domain Summary
This codebase is a CLI for running and maintaining the local Unoplat Code Confluence application. It manages GitHub release discovery, pins and repairs Docker Compose assets for the Flow Bridge, query engine, and frontend services, and opens browser-based setup pages for repository token and model-provider configuration.
Unoplat Code Confluence CLI manages a local Docker Compose deployment for repository-aware AI code assistance, including Flow Bridge, a query engine, and a frontend. It registers and refreshes Git repositories, verifies repository and model-provider credentials, tracks GitHub release manifests and installed state, and initiates AGENTS.md-generation workflows that raise pull requests.

## Data Model References
### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L27-L32`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L35-L40`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L43-L46`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L49-L53`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L56-L61`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L64-L70`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L73-L80`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L83-L97`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L100-L114`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/app_runtime.py#L117-L120`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/setup_runtime.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/setup_runtime.py#L11-L18`
### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/backend/flow_bridge_client.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/backend/flow_bridge_client.py#L16-L20`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/backend/flow_bridge_client.py#L23-L29`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/cli_app/context.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/cli_app/context.py#L19-L23`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L14-L19`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L22-L27`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L30-L33`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L36-L40`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L43-L48`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L51-L57`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L60-L67`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L70-L73`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/release.py#L76-L79`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/repository.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/repository.py#L10-L72`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L9-L18`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L21-L29`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L32-L38`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L41-L51`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L54-L66`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L69-L75`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L78-L86`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L89-L95`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/results.py#L98-L105`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/setup.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/domain/setup.py#L6-L11`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/ports/http_client.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-cli/src/unoplat_code_confluence_cli/ports/http_client.py#L8-L15`
4 changes: 2 additions & 2 deletions unoplat-code-confluence-cli/dependencies_overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
- **Package management**: Use `uv` as the package manager for this codebase.
- **click**: Purpose: A Python package for building composable command-line interfaces with minimal code. It provides automatic help-page generation, nested commands, and support for lazy-loaded subcommands.
- **httpx2**: Purpose: A next-generation HTTP client for Python. It provides synchronous and asynchronous APIs, with support for both HTTP/1.1 and HTTP/2. Official docs: https://httpx2.pydantic.dev/ ; PyPI: https://pypi.org/project/httpx2/
- **platformdirs**: Purpose: A Python library for determining platform-specific system directories, such as user data, configuration, cache, and log locations. It resolves the correct paths for macOS, Windows, Linux/Unix, and Android, with `_dir` and `_path` variants for each directory.
- **platformdirs**: Purpose: A Python library for determining platform-specific system directories, such as user data, configuration, cache, and log locations. It resolves the correct paths for macOS, Windows, Linux/Unix, and Android, with _dir and _path variants for each directory.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Keep _dir and _path formatted as code.

The removed backticks cause Markdown emphasis parsing and trigger MD037. Restore inline-code formatting around both API suffixes.

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 6-6: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@unoplat-code-confluence-cli/dependencies_overview.md` at line 6, Restore
inline-code formatting around the _dir and _path API suffixes in the
platformdirs description, using backticks so both identifiers render as code and
avoid Markdown emphasis parsing.

Source: Linters/SAST tools

- **pydantic**: Purpose: Python data validation and settings management library built around type hints. It validates, parses, and serializes structured data using Python models and can generate JSON Schema.
- **pydantic-settings**: Purpose: Provides Pydantic’s settings management via `BaseSettings`, letting you load configuration from environment variables, dotenv files, and secrets files. It also supports custom settings sources and priority control for how values are resolved.
- **pydantic-settings**: Purpose: Provides Pydantic’s settings management via BaseSettings, letting you load configuration from environment variables, dotenv files, and secrets files. It also supports custom settings sources and priority control for how values are resolved.
- **python-on-whales**: Purpose: A Docker client for Python with a 1:1 mapping to the Docker CLI. It provides a typed, object-oriented API for common Docker operations like run, build, compose, and swarm management.
5 changes: 4 additions & 1 deletion unoplat-code-confluence-commons/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ This project uses Backlog.md MCP for all task and project management. Before cre
<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:BEGIN -->
<CRITICAL_INSTRUCTION>

> Generated from branch `dev` at commit `3bbc2c8ae5f6fc7e94628c3b07a936ca5bdbcd02` (2026-06-09). Content may become stale as new commits land.
> Generated from branch `dev` at commit `5ecdba39d57f50c5188a8e32b9dd4f52d01611fe` (2026-07-18). Content may become stale as new commits land.

</CRITICAL_INSTRUCTION>

Expand Down Expand Up @@ -63,4 +63,7 @@ See [`business_domain_references.md`](./business_domain_references.md) for the s
## App Interfaces
See [`app_interfaces.md`](./app_interfaces.md) for the canonical interface and endpoint reference.

## Architecture
See [`architecture.md`](./architecture.md) for the canonical system architecture diagram.

<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:END -->
14 changes: 7 additions & 7 deletions unoplat-code-confluence-commons/business_domain_references.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# Business Domain References

## Domain Summary
This codebase supports Code Confluence, a repository ingestion and code-intelligence platform. It centers on persisting Git repositories, codebases, workflow runs, and agent execution state while cataloging framework features, language/package-manager metadata, and detected source-code spans. It also includes supporting operational models for credentials, feature flags, and AGENTS.md PR/publication tracking.
This package supports Code Confluence, a repository-ingestion and code-intelligence platform for analyzing source repositories and their codebases. It models repositories, files, language and package metadata, framework feature catalogs, detected source-code spans, and confidence/evidence for feature usage. It also manages workflow execution, progress and event histories, agent output snapshots and AGENTS.md publication metadata, with credentials and feature flags supporting operations.

## Data Model References
### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/data_model_position.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/data_model_position.py#L8-L14`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L51-L76`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L99-L169`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L172-L218`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L221-L239`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L242-L268`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L271-L290`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L58-L99`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L135-L210`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L213-L260`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L263-L281`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L284-L310`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/engine_models.py#L313-L332`

### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/framework_models.py`
- `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-commons/src/unoplat_code_confluence_commons/base_models/framework_models.py#L32-L54`
Expand Down
9 changes: 6 additions & 3 deletions unoplat-code-confluence-docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Reference details: see `business_logic_references.md`.
<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:BEGIN -->
<CRITICAL_INSTRUCTION>

> Generated from branch `dev` at commit `3bbc2c8ae5f6fc7e94628c3b07a936ca5bdbcd02` (2026-06-09). Content may become stale as new commits land.
> Generated from branch `dev` at commit `5ecdba39d57f50c5188a8e32b9dd4f52d01611fe` (2026-07-18). Content may become stale as new commits land.

</CRITICAL_INSTRUCTION>

Expand All @@ -46,10 +46,10 @@ Reference details: see `business_logic_references.md`.
- `bun run dev` (working directory: repo root; config: `package.json`)

### Test
- Not detected
- `vp test` (working directory: repo root; config: `vite.config.ts`; requires the Vite+ `vp` CLI)

### Lint
- Not detected
- `vp check` (working directory: repo root; config: `vite.config.ts`; runs Vite+ validation including linting; requires the Vite+ `vp` CLI)

### Type Check
- `bun run types:check` (working directory: repo root; config: `package.json`)
Expand All @@ -69,6 +69,9 @@ See [`business_domain_references.md`](./business_domain_references.md) for the s
## App Interfaces
See [`app_interfaces.md`](./app_interfaces.md) for the canonical interface and endpoint reference.

## Architecture
See [`architecture.md`](./architecture.md) for the canonical system architecture diagram.

<!-- UNOPLAT_CODE_CONFLUENCE_CONTEXT:END -->

<!--VITE PLUS START-->
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Business Domain References

## Domain Summary
This codebase powers the documentation site for Unoplat Code Confluence, a developer tool for AI-assisted code understanding and AGENTS.md generation. Its data models mostly cover docs-site content and presentation metadata—changelog entries, announcement banners, SEO settings, route definitions, and framework catalog rows—plus reusable data-table filtering primitives used to navigate that content. The dominant domain is product documentation and release communication for a code-context engine aimed at Python and TypeScript codebases.
This repository powers the documentation site for Unoplat Code Confluence, a code-context engine that helps AI agents understand Python and TypeScript codebases and generate AGENTS.md guidance. Its models support documentation delivery: framework and library catalog entries, searchable/filterable tables, release changelogs, site announcements, and page SEO metadata. The dominant domain is developer-product documentation and release communication for AI-assisted code understanding.

## Data Model References
### `/opt/unoplat/repositories/unoplat-code-confluence/unoplat-code-confluence-docs/src/components/data-table-filter/core/filters.ts`
Expand Down
Loading
Loading