[Improvement] Enforce Python module boundaries in CI and modularize gpt-rag-ui
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 321
- Avg merge
- 6h 22m
- Merged PRs (30d)
- 26
Description
## Summary
Complete the remaining Python modularization work by:
1. enforcing the existing architecture and error-handling rules through CI; and
2. migrating `gpt-rag-ui` from flat root modules to a structured `src` package.
The orchestrator structure, shared audit contracts, existing typed contracts, and ADRs should be reused rather than replaced.
## Why will we implement this?
- **Problem / opportunity:**
- Current Python CI workflows primarily run tests but do not enforce linting, static typing, import cycles, or documented package boundaries.
- Architecture and error-handling expectations are documented but depend on manual review.
- `gpt-rag-ui` still contains most runtime modules at the repository root, unlike the structured orchestrator layout.
- **Business value / outcome:**
- Prevent architecture drift.
- Detect type and dependency problems during pull requests.
- Make the UI code easier to navigate and maintain.
- Enforce consistent error behavior automatically.
- **Success metrics (how we know it worked):**
- All three Python repositories run linting and static type checking in CI.
- CI detects import cycles and prohibited package dependencies.
- Blind or overly broad exception handling is rejected or explicitly justified.
- `gpt-rag-ui` runtime code is packaged under `src/`.
- Existing APIs, imports, configuration, and deployment behavior remain compatible.
## What does it do? (Functional Overview)
- **Core behavior:**
1. Add Ruff configuration and required CI checks to:
- `gpt-rag-orchestrator`
- `gpt-rag-ingestion`
- `gpt-rag-ui`
2. Add static type checking using an incremental baseline:
- begin with the currently typed modules;
- prevent new violations;
- gradually expand blocking coverage.
3. Add automated import checks:
- detect circular imports;
- encode the boundaries already documented in `AGENTS.md`;
- prevent imports from another package's internal modules.
4. Strengthen error-handling enforcement:
- enable checks for blind exception handlers;
- require explicit handling or documented exceptions;
- add targeted tests for public boundaries that must not return success-shaped fallbacks.
5. Migrate `gpt-rag-ui` to a structure such as:
```text
src/
gpt_rag_ui/
api/
auth/
clients/
services/
telemetry/
util/
tests/
```
6. Keep `main.py` and `app.py` as thin compatibility or startup entry points while internal imports move to the package.
7. Complete the migration through incremental pull requests so each step remains independently deployable.
- **Data collection / storage needs:** None.
- **Data analysis / reporting needs:** CI should expose lint, typing, import-boundary, and test results.
- **Nice to have (stretch goals):**
- Vendor the existing conversations-panel contract in `gpt-rag-ui` and generate typed UI models.
- Apply the same `src` layout to ingestion after evaluating compatibility impact.
- Reuse a common CI configuration across the Python repositories.
## Out of scope
- Replacing the existing audit and telemetry contracts.
- Reorganizing the orchestrator package structure again.
- Creating a shared cross-repository JWT implementation.
- Creating a new shared Azure client repository.
- Changing the current multi-repository topology.
## Components
- **Components (check all that apply):**
- [x] gpt-rag-orchestrator
- [x] gpt-rag-ingestion
- [x] gpt-rag-ui
- [ ] gpt-rag-mcp
Contributor guide
Research direction
Start by reading the existing CI workflows, AGENTS.md, typed modules, audit contracts, and ADRs across the three named repositories. Then inspect gpt-rag-ui's root runtime modules plus main.py and app.py to map the proposed src/gpt_rag_ui structure. Done means CI reports lint, typing, import-boundary, exception, and test results while UI imports, APIs, configuration, and deployment remain compatible.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend, ci-cd, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100