Decision Management Interface¶
Referenced Files in This Document - Decidir.tsx - Historico.tsx - ActionBadge.tsx - StatusBadge.tsx - TypeBadge.tsx - decision.py - confidence.py - decisions.py - history.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py - decisions_svc.py - history.py
Table of Contents¶
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction¶
This document explains the decision management interface, focusing on the end-to-end workflow for reviewing decisions, previewing files, displaying metadata and AI confidence scores, approving or rejecting items (including batch operations), tracking decision history and audit trails, filtering and searching decisions, status and action badges, real-time updates, conflict resolution, exporting reports, extending decision types, customizing workflows, and integrating with external systems for automated processing.
The system is composed of: - A web dashboard UI that renders review pages, badges, dialogs, and controls. - A FastAPI service exposing routes for decisions and history. - Shared models and schemas defining data contracts. - Database access modules for persistence. - Core logic for decisions and confidence scoring.
Project Structure¶
The decision management feature spans multiple layers: - Frontend pages: Decidir.tsx (review page), Historico.tsx (history page). - UI components: ActionBadge.tsx, StatusBadge.tsx, TypeBadge.tsx. - Service routes: decisions.py, history.py. - Core logic: decision.py, confidence.py. - Shared contracts: models/decision.py, models/history.py, schemas/decision.py, schemas/history.py. - Data access: decisions_db.py, history_db.py. - Dashboard services (UI integration): decisions_svc.py, history.py.
graph TB
subgraph "Frontend"
D["Decidir.tsx"]
H["Historico.tsx"]
AB["ActionBadge.tsx"]
SB["StatusBadge.tsx"]
TB2["TypeBadge.tsx"]
end
subgraph "Service"
DR["routes/decisions.py"]
HR["routes/history.py"]
DC["core/decision.py"]
CF["core/confidence.py"]
end
subgraph "Shared Contracts"
DM["models/decision.py"]
HM["models/history.py"]
DS["schemas/decision.py"]
HS["schemas/history.py"]
end
subgraph "Data Access"
DDB["database/decisions_db.py"]
HDB["database/history_db.py"]
end
D --> DR
H --> HR
D --> AB
D --> SB
D --> TB2
DR --> DC
DR --> CF
DR --> DM
DR --> DS
DR --> DDB
HR --> HM
HR --> HS
HR --> HDB
Diagram sources - Decidir.tsx - Historico.tsx - ActionBadge.tsx - StatusBadge.tsx - TypeBadge.tsx - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py
Section sources - Decidir.tsx - Historico.tsx - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py
Core Components¶
- Review Page (Decidir.tsx): Presents a list of pending decisions with file preview, metadata display, AI confidence visualization, filters/search, and approval/rejection actions including batch operations. It integrates with backend routes to submit decisions and fetch updated lists.
- History Page (Historico.tsx): Displays past decisions and audit trail entries, supports filtering by date, user, and decision type, and provides export capabilities.
- Badges:
- ActionBadge.tsx: Renders interactive action indicators (approve/reject) and contextual cues.
- StatusBadge.tsx: Visualizes decision statuses (e.g., pending, approved, rejected).
- TypeBadge.tsx: Indicates decision types (e.g., match, rename, skip).
- Service Routes:
- decisions.py: Endpoints for listing decisions, submitting approvals/rejections, and batch operations.
- history.py: Endpoints for querying history and exporting reports.
- Core Logic:
- decision.py: Business rules for applying decisions, updating state, and recording outcomes.
- confidence.py: Computes and formats AI confidence metrics used in the UI.
- Shared Contracts:
- Models and schemas define the shape of decisions, history entries, and request/response payloads.
- Data Access:
- decisions_db.py and history_db.py implement persistence for decisions and history records.
Section sources - Decidir.tsx - Historico.tsx - ActionBadge.tsx - StatusBadge.tsx - TypeBadge.tsx - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py
Architecture Overview¶
The decision management flow connects the frontend review UI to backend routes, core logic, and persistence.
sequenceDiagram
participant U as "User"
participant FE as "Decidir.tsx"
participant API as "routes/decisions.py"
participant CORE as "core/decision.py"
participant CONF as "core/confidence.py"
participant DB as "database/decisions_db.py"
U->>FE : Open review page
FE->>API : GET /decisions?filters...
API->>CORE : Load pending decisions
CORE->>CONF : Compute confidence scores
CONF-->>CORE : Scores
CORE-->>API : Decisions with metadata
API-->>FE : JSON payload
FE->>FE : Render previews, metadata, badges, confidence bars
U->>FE : Approve/Reject single or batch
FE->>API : POST /decisions/approve|reject {ids}
API->>CORE : Apply decision(s)
CORE->>DB : Persist outcome and audit entry
DB-->>CORE : OK
CORE-->>API : Updated state
API-->>FE : Success + updated list
FE->>FE : Refresh view and badges
Diagram sources - Decidir.tsx - decisions.py - decision.py - confidence.py - decisions_db.py
Detailed Component Analysis¶
Review Workflow (Decidir.tsx)¶
- File Preview: The page loads media/document metadata and renders a preview pane. It uses the decision model fields to present titles, paths, thumbnails, and related attributes.
- Metadata Display: Key-value pairs are shown for quick context (e.g., source, size, timestamps).
- AI Confidence Visualization: Confidence scores computed by the core module are rendered as progress bars or numeric indicators.
- Filtering and Search: Users can filter by decision type, status, date range, and search by text across metadata fields.
- Approval/Rejection Actions:
- Single item: Click an action badge to approve or reject.
- Batch operations: Select multiple items and apply a decision to all selected.
- Real-time Updates: After submission, the UI refreshes the list and updates badges without full reloads.
flowchart TD
Start(["Open Review Page"]) --> Fetch["Fetch decisions with filters"]
Fetch --> Render["Render previews, metadata, badges"]
Render --> UserAction{"User Action?"}
UserAction --> |Approve| SubmitA["Submit approve"]
UserAction --> |Reject| SubmitR["Submit reject"]
UserAction --> |Batch| SubmitB["Submit batch approve/reject"]
SubmitA --> UpdateA["Persist and update list"]
SubmitR --> UpdateR["Persist and update list"]
SubmitB --> UpdateB["Persist and update list"]
UpdateA --> Refresh["Refresh UI and badges"]
UpdateR --> Refresh
UpdateB --> Refresh
Refresh --> End(["Ready for next review"])
Diagram sources - Decidir.tsx - decisions.py - decision.py - decisions_db.py
Section sources - Decidir.tsx - decisions.py - decision.py - decisions_db.py
History and Audit Trail (Historico.tsx)¶
- History Listing: Displays past decisions with timestamps, users, and outcomes.
- Filtering and Search: Supports queries by date, user, decision type, and free-text search.
- Export Functionality: Allows exporting filtered results to CSV/JSON for reporting.
- Audit Trail: Each decision change is recorded with actor, timestamp, and rationale when provided.
sequenceDiagram
participant U as "User"
participant HE as "Historico.tsx"
participant HR as "routes/history.py"
participant HM as "models/history.py"
participant HS as "schemas/history.py"
participant HDB as "database/history_db.py"
U->>HE : Open history page
HE->>HR : GET /history?filters...
HR->>HDB : Query history entries
HDB-->>HR : Records
HR-->>HE : JSON payload
HE->>HE : Render table, badges, filters
U->>HE : Export report
HE->>HR : GET /history/export?filters...
HR->>HDB : Generate export dataset
HDB-->>HR : Dataset
HR-->>HE : File stream or download link
Diagram sources - Historico.tsx - history.py - history.py - history.py - history_db.py
Section sources - Historico.tsx - history.py - history.py - history.py - history_db.py
Badges and Visual Indicators¶
- ActionBadge.tsx: Provides clickable actions for approve/reject and visual feedback on hover/active states.
- StatusBadge.tsx: Shows current decision status with color-coded labels.
- TypeBadge.tsx: Identifies decision type (e.g., match, rename, skip) for quick scanning.
classDiagram
class ActionBadge {
+render(action)
+onClick()
}
class StatusBadge {
+render(status)
}
class TypeBadge {
+render(type)
}
ActionBadge <.. StatusBadge : "used together"
ActionBadge <.. TypeBadge : "used together"
Diagram sources - ActionBadge.tsx - StatusBadge.tsx - TypeBadge.tsx
Section sources - ActionBadge.tsx - StatusBadge.tsx - TypeBadge.tsx
Confidence Scoring Visualization¶
- Computation: The core confidence module calculates scores based on matching heuristics or ML outputs.
- Presentation: The review page displays confidence as numeric values and visual bars to guide reviewers.
flowchart TD
Input["Input features/metadata"] --> Score["Compute confidence score"]
Score --> Normalize["Normalize to 0-100%"]
Normalize --> Render["Render bar + label"]
Render --> Threshold{"Above threshold?"}
Threshold --> |Yes| Suggest["Suggest auto-approve"]
Threshold --> |No| Flag["Flag for human review"]
Diagram sources - confidence.py - Decidir.tsx
Section sources - confidence.py - Decidir.tsx
Conflict Resolution Mechanisms¶
- Detection: When two users attempt to modify the same decision concurrently, the system detects conflicts via versioning or last-write-wins policies.
- Resolution:
- Last-write-wins: The latest accepted change prevails; earlier changes are logged as superseded.
- Merge prompts: For complex cases, the UI may prompt the reviewer to choose between conflicting options.
- Auditability: All conflicts and resolutions are recorded in the history with details.
sequenceDiagram
participant U1 as "Reviewer A"
participant U2 as "Reviewer B"
participant API as "routes/decisions.py"
participant CORE as "core/decision.py"
participant DB as "database/decisions_db.py"
U1->>API : Submit decision v1
API->>CORE : Apply v1
CORE->>DB : Write v1
U2->>API : Submit decision v2
API->>CORE : Detect conflict
CORE-->>API : Conflict detected
API-->>U2 : Prompt resolution
U2->>API : Choose winner
API->>CORE : Apply resolved change
CORE->>DB : Record resolution
Diagram sources - decisions.py - decision.py - decisions_db.py
Section sources - decisions.py - decision.py - decisions_db.py
Real-time Updates¶
- Strategy: After successful submissions, the frontend refreshes the affected items and re-renders badges and confidence indicators.
- Implementation: The review page triggers targeted updates rather than full-page reloads to maintain responsiveness.
sequenceDiagram
participant FE as "Decidir.tsx"
participant API as "routes/decisions.py"
participant DB as "database/decisions_db.py"
FE->>API : POST approve/reject
API->>DB : Persist change
DB-->>API : OK
API-->>FE : Success response
FE->>FE : Patch local state and re-render
Diagram sources - Decidir.tsx - decisions.py - decisions_db.py
Section sources - Decidir.tsx - decisions.py - decisions_db.py
Extending Decision Types¶
- Add new types in shared models and schemas to include additional fields and validation rules.
- Extend core decision logic to handle new workflows and side effects.
- Update UI badges and filters to recognize and render new types.
classDiagram
class DecisionModel {
+id
+type
+status
+metadata
+confidence
}
class NewDecisionType {
+custom_field_1
+custom_field_2
}
DecisionModel <|-- NewDecisionType : "extends"
Diagram sources - decision.py - decision.py - decision.py
Section sources - decision.py - decision.py - decision.py
Customizing Decision Workflows¶
- Configure thresholds for auto-approval based on confidence scores.
- Define conditional routing for different decision types (e.g., high-confidence matches auto-approved, low-confidence flagged).
- Introduce multi-step reviews for sensitive decisions.
flowchart TD
Start(["New Decision"]) --> Classify["Classify type"]
Classify --> Score["Compute confidence"]
Score --> Threshold{"Score >= threshold?"}
Threshold --> |Yes| Auto["Auto-approve"]
Threshold --> |No| Manual["Route to manual review"]
Auto --> Log["Record audit entry"]
Manual --> Review["Human review"]
Review --> Outcome{"Approve/Reject"}
Outcome --> Log
Diagram sources - decision.py - confidence.py - decisions.py
Section sources - decision.py - confidence.py - decisions.py
Integrating with External Systems¶
- Automated Processing: Call external APIs to enrich metadata or trigger downstream actions upon decision outcomes.
- Webhooks: Emit events when decisions are finalized for integration with other tools.
- Sync: Periodically sync decisions with external catalogs or libraries.
sequenceDiagram
participant FE as "Decidir.tsx"
participant API as "routes/decisions.py"
participant EXT as "External System"
participant DB as "database/decisions_db.py"
FE->>API : Submit decision
API->>EXT : Trigger automation (webhook/API)
EXT-->>API : Acknowledge
API->>DB : Persist decision and audit
DB-->>API : OK
API-->>FE : Success
Diagram sources - decisions.py - decisions_db.py
Section sources - decisions.py - decisions_db.py
Dependency Analysis¶
The decision management feature depends on clear separation between UI, service routes, core logic, shared contracts, and database access.
graph LR
FE["Decidir.tsx / Historico.tsx"] --> SVC["routes/decisions.py / routes/history.py"]
SVC --> CORE["core/decision.py / core/confidence.py"]
SVC --> SCHEMA["schemas/decision.py / schemas/history.py"]
SVC --> MODEL["models/decision.py / models/history.py"]
SVC --> DB["database/decisions_db.py / database/history_db.py"]
Diagram sources - Decidir.tsx - Historico.tsx - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py
Section sources - Decidir.tsx - Historico.tsx - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py - decision.py - history.py - decisions_db.py - history_db.py
Performance Considerations¶
- Pagination and Lazy Loading: For large decision sets, paginate listings and load previews on demand.
- Efficient Filtering: Push filter parameters to the backend to reduce payload sizes.
- Caching: Cache frequently accessed metadata and confidence scores where appropriate.
- Batch Operations: Prefer batch endpoints to minimize network round-trips.
- Optimistic UI Updates: Update UI immediately after submission and reconcile server state on success.
Troubleshooting Guide¶
- Missing Previews: Ensure metadata fields are populated and file paths are accessible. Check network requests for errors.
- Incorrect Badges: Verify decision status and type mappings in shared schemas and UI components.
- Confidence Mismatch: Confirm confidence computation inputs and normalization ranges.
- Conflicts: Inspect audit logs for overlapping submissions and adjust concurrency handling if needed.
- Export Failures: Validate filter parameters and ensure sufficient permissions for generating reports.
Section sources - decisions.py - history.py - decision.py - confidence.py - decision.py - history.py
Conclusion¶
The decision management interface provides a comprehensive workflow for reviewing, approving, and rejecting decisions with rich metadata, AI confidence visualization, and robust auditability. It supports batch operations, filtering, real-time updates, conflict resolution, and export functionality. Extensibility is achieved through well-defined models and schemas, while integrations enable automation and synchronization with external systems.
Appendices¶
API Reference Summary¶
- Decisions
- List decisions with filters and pagination.
- Approve/reject single or batch decisions.
- Retrieve confidence scores and metadata.
- History
- Query historical decisions with filters.
- Export reports in CSV/JSON.
Section sources - decisions.py - history.py
Data Model Summary¶
- Decision: id, type, status, metadata, confidence, timestamps.
- History Entry: id, decision_id, actor, action, timestamp, notes.
Section sources - decision.py - history.py - decision.py - history.py