# jesus-alva/rioproyect architecture

> Architecture diagram of the GitHub repository jesus-alva/rioproyect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jesus-alva/rioproyect
- Repository: https://github.com/jesus-alva/rioproyect

## Overview

Rio Claro is a branch-scoped distributor operations system with a Next.js role-based workspace and FastAPI backend. Users authenticate, then work through role-specific capabilities: invoice upload/review and director reporting, inventory, agent chat, complaint intake and follow-up, and administrator access management. The excerpts establish backend routing and persistence layers; the README documents key API workflows and Azure integrations. Some frontend-to-API paths and unsampled subsystem internals are therefore omitted or shown only where explicitly documented.

Main entry points: [`backend/app/main.py`](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/main.py) (API orchestration), [`frontend/components/ProtectedDashboard.jsx`](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ProtectedDashboard.jsx) (Role dashboard), [`backend/app/auth.py`](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/auth.py) (Authentication and roles), [`frontend/app/login/page.jsx`](https://github.com/jesus-alva/rioproyect/blob/main/frontend/app/login/page.jsx) (Login and registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_login["Login and registration<br/>[page.jsx]"]
  node_workspace["Role dashboard"]
  node_user_admin["User administration"]
  node_invoices_ui["Invoice workspace"]
  node_chat_ui["Agent chat<br/>[ChatPanel.jsx]"]
  node_complaint_ui["Complaint inbox<br/>[ComplaintInbox.jsx]"]
end

subgraph group_identity["Identity and access"]
  node_session["Session storage<br/>[authSession.js]"]
  node_auth_api["Authentication and roles<br/>[auth.py]"]
  node_branch_policy["Branch authorization<br/>[branches.py]"]
end

subgraph group_operations["Operations workflows"]
  node_invoice_processing["Invoice processing<br/>[invoice_upload.py]"]
  node_complaint_analysis["Complaint analysis"]
  node_agent_registry["Agent roles<br/>[roles.py]"]
end

subgraph group_platform["Backend platform"]
  node_api["API orchestration<br/>[main.py]"]
  node_database[("Application database<br/>[database.py]")]
end

node_users(("Staff and customers"))
node_azure_foundry{{"Azure AI Foundry"}}
node_azure_services{{"Azure storage, search and document AI"}}

node_users -->|"sign in or register"| node_login
node_login -->|"authenticates"| node_auth_api
node_login -->|"saves session"| node_session
node_workspace -->|"reads session"| node_session
node_workspace -->|"renders admin tools"| node_user_admin
node_workspace -->|"renders invoice tools"| node_invoices_ui
node_workspace -->|"renders chat"| node_chat_ui
node_workspace -->|"renders inbox"| node_complaint_ui
node_user_admin -->|"updates access"| node_auth_api
node_invoices_ui -.->|"uploads and reviews"| node_api
node_chat_ui -.->|"sends chat requests"| node_api
node_complaint_ui -->|"manages complaints"| node_api
node_workspace -->|"requests sales report"| node_api
node_api -->|"routes authentication"| node_auth_api
node_api -->|"routes invoice upload"| node_invoice_processing
node_api -->|"analyzes complaints"| node_complaint_analysis
node_api -->|"reads and writes records"| node_database
node_auth_api -->|"persists accounts"| node_database
node_auth_api -->|"validates assignments"| node_branch_policy
node_api -->|"selects agent roles"| node_agent_registry
node_complaint_analysis -->|"classifies complaints"| node_azure_foundry
node_invoice_processing -.->|"uses document services"| node_azure_services

click node_login "https://github.com/jesus-alva/rioproyect/blob/main/frontend/app/login/page.jsx"
click node_workspace "https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ProtectedDashboard.jsx"
click node_user_admin "https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/AdminUserManagement.jsx"
click node_invoices_ui "https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/InvoiceWorkspace.jsx"
click node_chat_ui "https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ChatPanel.jsx"
click node_complaint_ui "https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ComplaintInbox.jsx"
click node_session "https://github.com/jesus-alva/rioproyect/blob/main/frontend/lib/authSession.js"
click node_auth_api "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/auth.py"
click node_branch_policy "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/branches.py"
click node_invoice_processing "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/invoice_upload.py"
click node_complaint_analysis "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/complaint_analysis.py"
click node_agent_registry "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/roles.py"
click node_api "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/main.py"
click node_database "https://github.com/jesus-alva/rioproyect/blob/main/backend/app/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_login,node_workspace,node_user_admin,node_invoices_ui,node_chat_ui,node_complaint_ui toneBlue
class node_session,node_auth_api,node_branch_policy,node_azure_services toneAmber
class node_invoice_processing,node_complaint_analysis,node_agent_registry toneMint
class node_api,node_database toneRose
class node_users,node_azure_foundry toneIndigo
```

## Components

### User experience

- [Login and registration](https://github.com/jesus-alva/rioproyect/blob/main/frontend/app/login/page.jsx): `frontend/app/login/page.jsx`
- [Role dashboard](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ProtectedDashboard.jsx): `frontend/components/ProtectedDashboard.jsx`
- [User administration](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/AdminUserManagement.jsx): `frontend/components/AdminUserManagement.jsx`
- [Invoice workspace](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/InvoiceWorkspace.jsx): `frontend/components/InvoiceWorkspace.jsx`
- [Agent chat](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ChatPanel.jsx): `frontend/components/ChatPanel.jsx`
- [Complaint inbox](https://github.com/jesus-alva/rioproyect/blob/main/frontend/components/ComplaintInbox.jsx): `frontend/components/ComplaintInbox.jsx`

### Identity and access

- [Session storage](https://github.com/jesus-alva/rioproyect/blob/main/frontend/lib/authSession.js): `frontend/lib/authSession.js`
- [Authentication and roles](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Branch authorization](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/branches.py): `backend/app/branches.py`

### Operations workflows

- [Invoice processing](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/invoice_upload.py): `backend/app/invoice_upload.py`
- [Complaint analysis](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/complaint_analysis.py): `backend/app/complaint_analysis.py`
- [Agent roles](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/roles.py): `backend/app/roles.py`

### Backend platform

- [API orchestration](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/main.py): `backend/app/main.py`
- [Application database](https://github.com/jesus-alva/rioproyect/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Staff and customers**
- **Azure AI Foundry**
- **Azure storage, search and document AI**

## Connections

- Staff and customers → Login and registration: sign in or register (evidence: `frontend/app/login/page.jsx`)
- Login and registration → Authentication and roles: authenticates (evidence: `README.md`)
- Login and registration → Session storage: saves session (evidence: `frontend/app/login/page.jsx`)
- Role dashboard → Session storage: reads session (evidence: `frontend/components/ProtectedDashboard.jsx`)
- Role dashboard → User administration: renders admin tools (evidence: `frontend/components/ProtectedDashboard.jsx`)
- Role dashboard → Invoice workspace: renders invoice tools (evidence: `frontend/components/ProtectedDashboard.jsx`)
- Role dashboard → Agent chat: renders chat (evidence: `frontend/components/ProtectedDashboard.jsx`)
- Role dashboard → Complaint inbox: renders inbox (evidence: `frontend/components/ProtectedDashboard.jsx`)
- User administration → Authentication and roles: updates access (evidence: `frontend/components/AdminUserManagement.jsx`)
- Invoice workspace → API orchestration: uploads and reviews
- Agent chat → API orchestration: sends chat requests
- Complaint inbox → API orchestration: manages complaints (evidence: `README.md`)
- Role dashboard → API orchestration: requests sales report (evidence: `README.md`)
- API orchestration → Authentication and roles: routes authentication (evidence: `backend/app/main.py`)
- API orchestration → Invoice processing: routes invoice upload (evidence: `backend/app/main.py`)
- API orchestration → Complaint analysis: analyzes complaints (evidence: `backend/app/main.py`)
- API orchestration → Application database: reads and writes records (evidence: `backend/app/main.py`)
- Authentication and roles → Application database: persists accounts (evidence: `backend/app/auth.py`)
- Authentication and roles → Branch authorization: validates assignments (evidence: `backend/app/auth.py`)
- API orchestration → Agent roles: selects agent roles (evidence: `backend/app/main.py`)
- Complaint analysis → Azure AI Foundry: classifies complaints (evidence: `README.md`)
- Invoice processing → Azure storage, search and document AI: uses document services
