# ali-elnopy/agency architecture

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

- Interactive diagram: https://gitdiagram.com/ali-elnopy/agency
- Repository: https://github.com/ali-elnopy/agency

## Overview

ORVIA is an agency-management workspace for staff and clients. The user-facing flow spans sign-in and role-aware workspace views, then brand and client management, content planning and briefs, task execution, and client review. The backend provides authentication and agency data APIs backed by PostgreSQL; the frontend also has browser-local workspace state, which the README says is not yet shared across devices. The graph retains documented product areas, but several frontend/backend connections and unsampled routes are omitted where the excerpts do not establish their wiring.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ali-elnopy/agency/blob/main/frontend/src/App.jsx) (Workspace shell), [`frontend/src/context/Sprint3Context.jsx`](https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/Sprint3Context.jsx) (Workflow state), [`frontend/src/pages/ClientPortalPage.jsx`](https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/ClientPortalPage.jsx) (Client portal), [`frontend/src/services/api.js`](https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspace"]
  node_webapp["Workspace shell<br/>[App.jsx]"]
  node_login["Sign-in view<br/>[LoginPage.jsx]"]
  node_clientportal["Client portal"]
  node_dashboard["Account dashboard<br/>[DashboardPage.jsx]"]
end

subgraph group_agency["Agency management"]
  node_brandsctx["Brands state<br/>[BrandsContext.jsx]"]
  node_workspacectx["Workspace state"]
  node_brandservice["Brand management<br/>[brands.service.js]"]
  node_teamservice["Team management<br/>[teams.service.js]"]
  node_users["User management"]
  node_dashboardservice["Dashboard data"]
end

subgraph group_content["Content workflow"]
  node_sprintctx["Workflow state<br/>[Sprint3Context.jsx]"]
  node_sprintdata["Workflow records<br/>[sprint3.js]"]
  node_briefs["AI brief generation"]
  node_campaigns["Campaign management"]
  node_plans["Content planning"]
  node_contentitems["Content items"]
  node_taskscontroller["Task endpoints"]
  node_tasksservice["Task workflow<br/>[tasks.service.js]"]
  node_platformaccounts["Social accounts"]
end

subgraph group_platform["API and persistence"]
  node_frontendapi["API client<br/>[api.js]"]
  node_sprintapi["Workflow API<br/>[sprint3Api.js]"]
  node_backend["Express API<br/>[app.js]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_identity["Identity and access"]
  node_authprovider["Auth provider<br/>[AuthProvider.jsx]"]
  node_authhook["Auth hook<br/>[useAuth.js]"]
  node_tokenstorage["Session storage<br/>[tokenStorage.js]"]
  node_authservice["Authentication<br/>[auth.service.js]"]
  node_authmodel["Session model<br/>[auth.model.js]"]
end

node_staff(("Agency staff"))
node_client(("Agency client"))

node_webapp -->|"renders"| node_login
node_webapp -->|"renders"| node_clientportal
node_webapp -->|"renders"| node_dashboard
node_webapp -->|"provides state"| node_sprintctx
node_webapp -->|"provides state"| node_brandsctx
node_webapp -->|"provides state"| node_workspacectx
node_webapp -->|"checks session"| node_tokenstorage
node_authprovider -->|"supplies context"| node_authhook
node_sprintctx -->|"uses records"| node_sprintdata
node_sprintctx -->|"calls"| node_frontendapi
node_sprintctx -->|"calls"| node_sprintapi
node_clientportal -->|"reads session"| node_authhook
node_clientportal -->|"checks mock mode"| node_frontendapi
node_frontendapi -->|"sends API requests"| node_backend
node_authservice -->|"manages sessions"| node_authmodel
node_taskscontroller -->|"dispatches"| node_tasksservice
node_briefs -.->|"persists data"| node_postgres
node_backend -->|"uses database"| node_postgres

click node_webapp "https://github.com/ali-elnopy/agency/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/LoginPage.jsx"
click node_clientportal "https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/ClientPortalPage.jsx"
click node_dashboard "https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_authprovider "https://github.com/ali-elnopy/agency/blob/main/frontend/src/auth/AuthProvider.jsx"
click node_authhook "https://github.com/ali-elnopy/agency/blob/main/frontend/src/hooks/useAuth.js"
click node_tokenstorage "https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/tokenStorage.js"
click node_brandsctx "https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/BrandsContext.jsx"
click node_workspacectx "https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/WorkspaceContext.jsx"
click node_sprintctx "https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/Sprint3Context.jsx"
click node_sprintdata "https://github.com/ali-elnopy/agency/blob/main/frontend/src/data/sprint3.js"
click node_frontendapi "https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/api.js"
click node_sprintapi "https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/sprint3Api.js"
click node_backend "https://github.com/ali-elnopy/agency/blob/main/backend/src/app.js"
click node_authservice "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/auth/auth.service.js"
click node_authmodel "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/auth/auth.model.js"
click node_brandservice "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/brands/brands.service.js"
click node_teamservice "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/teams/teams.service.js"
click node_users "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/users/users.controller.js"
click node_dashboardservice "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/dashboard/dashboard.service.js"
click node_briefs "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/brand-briefs/brand-briefs.service.js"
click node_campaigns "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/campaigns/campaigns.service.js"
click node_plans "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/content-plans/content-plans.service.js"
click node_contentitems "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/content-items/content-items.service.js"
click node_taskscontroller "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/tasks/tasks.controller.js"
click node_tasksservice "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/tasks/tasks.service.js"
click node_platformaccounts "https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/platform-accounts/platform-accounts.service.js"

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_webapp,node_login,node_clientportal,node_dashboard,node_client toneBlue
class node_brandsctx,node_workspacectx,node_brandservice,node_teamservice,node_users,node_dashboardservice toneAmber
class node_sprintctx,node_sprintdata,node_briefs,node_campaigns,node_plans,node_contentitems,node_taskscontroller,node_tasksservice,node_platformaccounts toneMint
class node_frontendapi,node_sprintapi,node_backend,node_postgres toneRose
class node_authprovider,node_authhook,node_tokenstorage,node_authservice,node_authmodel,node_staff toneIndigo
```

## Components

### Web workspace

- [Workspace shell](https://github.com/ali-elnopy/agency/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in view](https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/LoginPage.jsx): `frontend/src/pages/LoginPage.jsx`
- [Client portal](https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/ClientPortalPage.jsx): `frontend/src/pages/ClientPortalPage.jsx`
- [Account dashboard](https://github.com/ali-elnopy/agency/blob/main/frontend/src/pages/DashboardPage.jsx): `frontend/src/pages/DashboardPage.jsx`

### Agency management

- [Brands state](https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/BrandsContext.jsx): `frontend/src/context/BrandsContext.jsx`
- [Workspace state](https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/WorkspaceContext.jsx): `frontend/src/context/WorkspaceContext.jsx`
- [Brand management](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/brands/brands.service.js): `backend/src/modules/brands/brands.service.js`
- [Team management](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/teams/teams.service.js): `backend/src/modules/teams/teams.service.js`
- [User management](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/users/users.controller.js): `backend/src/modules/users/users.controller.js`
- [Dashboard data](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/dashboard/dashboard.service.js): `backend/src/modules/dashboard/dashboard.service.js`

### Content workflow

- [Workflow state](https://github.com/ali-elnopy/agency/blob/main/frontend/src/context/Sprint3Context.jsx): `frontend/src/context/Sprint3Context.jsx`
- [Workflow records](https://github.com/ali-elnopy/agency/blob/main/frontend/src/data/sprint3.js): `frontend/src/data/sprint3.js`
- [AI brief generation](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/brand-briefs/brand-briefs.service.js): `backend/src/modules/brand-briefs/brand-briefs.service.js`
- [Campaign management](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/campaigns/campaigns.service.js): `backend/src/modules/campaigns/campaigns.service.js`
- [Content planning](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/content-plans/content-plans.service.js): `backend/src/modules/content-plans/content-plans.service.js`
- [Content items](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/content-items/content-items.service.js): `backend/src/modules/content-items/content-items.service.js`
- [Task endpoints](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/tasks/tasks.controller.js): `backend/src/modules/tasks/tasks.controller.js`
- [Task workflow](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/tasks/tasks.service.js): `backend/src/modules/tasks/tasks.service.js`
- [Social accounts](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/platform-accounts/platform-accounts.service.js): `backend/src/modules/platform-accounts/platform-accounts.service.js`

### API and persistence

- [API client](https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Workflow API](https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/sprint3Api.js): `frontend/src/services/sprint3Api.js`
- [Express API](https://github.com/ali-elnopy/agency/blob/main/backend/src/app.js): `backend/src/app.js`
- **PostgreSQL**

### Identity and access

- [Auth provider](https://github.com/ali-elnopy/agency/blob/main/frontend/src/auth/AuthProvider.jsx): `frontend/src/auth/AuthProvider.jsx`
- [Auth hook](https://github.com/ali-elnopy/agency/blob/main/frontend/src/hooks/useAuth.js): `frontend/src/hooks/useAuth.js`
- [Session storage](https://github.com/ali-elnopy/agency/blob/main/frontend/src/services/tokenStorage.js): `frontend/src/services/tokenStorage.js`
- [Authentication](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/auth/auth.service.js): `backend/src/modules/auth/auth.service.js`
- [Session model](https://github.com/ali-elnopy/agency/blob/main/backend/src/modules/auth/auth.model.js): `backend/src/modules/auth/auth.model.js`

### Other components

- **Agency staff**
- **Agency client**

## Connections

- Workspace shell → Sign-in view: renders (evidence: `frontend/src/App.jsx`)
- Workspace shell → Client portal: renders (evidence: `frontend/src/App.jsx`)
- Workspace shell → Account dashboard: renders (evidence: `frontend/src/App.jsx`)
- Workspace shell → Workflow state: provides state (evidence: `frontend/src/App.jsx`)
- Workspace shell → Brands state: provides state (evidence: `frontend/src/App.jsx`)
- Workspace shell → Workspace state: provides state (evidence: `frontend/src/App.jsx`)
- Workspace shell → Session storage: checks session (evidence: `frontend/src/App.jsx`)
- Auth provider → Auth hook: supplies context (evidence: `frontend/src/hooks/useAuth.js`)
- Workflow state → Workflow records: uses records (evidence: `frontend/src/context/Sprint3Context.jsx`)
- Workflow state → API client: calls (evidence: `frontend/src/context/Sprint3Context.jsx`)
- Workflow state → Workflow API: calls (evidence: `frontend/src/context/Sprint3Context.jsx`)
- Client portal → Auth hook: reads session (evidence: `frontend/src/pages/ClientPortalPage.jsx`)
- Client portal → API client: checks mock mode (evidence: `frontend/src/pages/ClientPortalPage.jsx`)
- API client → Express API: sends API requests (evidence: `README.md`)
- Authentication → Session model: manages sessions (evidence: `backend/src/modules/auth/auth.service.js`)
- Task endpoints → Task workflow: dispatches (evidence: `backend/src/modules/tasks/tasks.controller.js`)
- AI brief generation → PostgreSQL: persists data
- Express API → PostgreSQL: uses database (evidence: `README.md`)
