# ahmedhrgx/pv-sharing architecture

> Architecture diagram of the GitHub repository ahmedhrgx/pv-sharing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmedhrgx/pv-sharing
- Repository: https://github.com/ahmedhrgx/pv-sharing

## Overview

Proper Voltage is a multi-tenant UPS battery-system customer portal. Integrators sign in, configure and size a project, save it as a draft, submit it for a quote that creates a HubSpot deal, and exchange project documents in a data room. The graph also preserves the company, location, and user administration capabilities. The README documents the web/API boundary and API ports-and-adapters structure; sampled source confirms quote submission, authorization, sizing, and document-provider behavior. Some unsampled service wiring is represented only where documented.

Main entry points: [`apps/api/src/app.module.ts`](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/app.module.ts) (REST API), [`apps/api/src/modules/projects/projects.controller.ts`](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/projects/projects.controller.ts) (Project workflow), [`apps/web/lib/data-source/api-source.ts`](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/lib/data-source/api-source.ts) (API data source), [`apps/web/app/(app)/projects/new/page.tsx`](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/app/(app)/projects/new/page.tsx) (Project workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Portal experience"]
  node_webprojects["Project workflow<br/>[page.tsx]"]
  node_calculatorui["Sizing calculator<br/>[CalculatorView.tsx]"]
  node_documentsui["Project data room<br/>[DocumentsView.tsx]"]
  node_adminui["Admin portal<br/>[CompaniesView.tsx]"]
  node_webapi["API data source<br/>[api-source.ts]"]
end

subgraph group_api["Portal API"]
  node_api["REST API<br/>[app.module.ts]"]
  node_auth["Token verification<br/>[auth.controller.ts]"]
  node_projects["Project workflow"]
  node_projectservice["Project service"]
  node_sizing["Sizing engine"]
  node_documents["Document service"]
end

subgraph group_admin["Tenant administration"]
  node_companies["Company management"]
  node_locations["Location management"]
  node_users["User management<br/>[users.service.ts]"]
end

subgraph group_integrations["External services"]
  node_postgres[("PostgreSQL")]
  node_cognito["Amazon Cognito"]
  node_hubspot["HubSpot CRM"]
  node_s3[("Amazon S3")]
end

subgraph group_shared["Shared domain"]
  node_contracts["Contracts and domain<br/>[contracts.ts]"]
end

node_integrator(("Integrator"))

node_integrator -->|"signs in"| node_cognito
node_integrator -->|"configures project"| node_webprojects
node_webprojects -->|"configures sizing"| node_calculatorui
node_webprojects -->|"manages files"| node_documentsui
node_webprojects -->|"requests data"| node_webapi
node_calculatorui -->|"saves configuration"| node_webapi
node_documentsui -->|"uploads and retrieves"| node_webapi
node_adminui -->|"manages tenants"| node_webapi
node_webapi -->|"REST requests"| node_api
node_api -->|"guards routes"| node_auth
node_api -->|"routes projects"| node_projects
node_api -->|"routes documents"| node_documents
node_api -->|"routes companies"| node_companies
node_api -->|"routes locations"| node_locations
node_api -->|"routes users"| node_users
node_projects -->|"invokes"| node_projectservice
node_projectservice -->|"reads and writes"| node_postgres
node_projects -->|"computes sizing"| node_sizing
node_projects -->|"submits quote"| node_hubspot
node_documents -.->|"stores documents"| node_s3
node_documents -.->|"stores files"| node_hubspot
node_companies -->|"reads and writes"| node_postgres
node_locations -->|"reads and writes"| node_postgres
node_users -->|"reads and writes"| node_postgres
node_auth -->|"verifies tokens"| node_cognito
node_projects -->|"uses shared types"| node_contracts
node_sizing -->|"uses sizing types"| node_contracts

click node_webprojects "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/app/(app)/projects/new/page.tsx"
click node_calculatorui "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/projects/calculator/CalculatorView.tsx"
click node_documentsui "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/projects/DocumentsView.tsx"
click node_adminui "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/companies/CompaniesView.tsx"
click node_webapi "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/lib/data-source/api-source.ts"
click node_api "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/app.module.ts"
click node_auth "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_projects "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/projects/projects.controller.ts"
click node_projectservice "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/projects/projects.service.ts"
click node_sizing "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/sizing/default-sizing.engine.ts"
click node_documents "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/documents/documents.service.ts"
click node_companies "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/companies/companies.controller.ts"
click node_locations "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/locations/locations.controller.ts"
click node_users "https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/users/users.service.ts"
click node_contracts "https://github.com/ahmedhrgx/pv-sharing/blob/main/packages/shared/src/contracts.ts"

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_webprojects,node_calculatorui,node_documentsui,node_adminui,node_webapi toneBlue
class node_api,node_auth,node_projects,node_projectservice,node_sizing,node_documents toneAmber
class node_companies,node_locations,node_users toneMint
class node_postgres,node_cognito,node_hubspot,node_s3 toneRose
class node_contracts,node_integrator toneIndigo
```

## Components

### Portal experience

- [Project workflow](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/app/(app)/projects/new/page.tsx): `apps/web/app/(app)/projects/new/page.tsx`
- [Sizing calculator](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/projects/calculator/CalculatorView.tsx): `apps/web/components/projects/calculator/CalculatorView.tsx`
- [Project data room](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/projects/DocumentsView.tsx): `apps/web/components/projects/DocumentsView.tsx`
- [Admin portal](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/components/companies/CompaniesView.tsx): `apps/web/components/companies/CompaniesView.tsx`
- [API data source](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/web/lib/data-source/api-source.ts): `apps/web/lib/data-source/api-source.ts`

### Portal API

- [REST API](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [Token verification](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Project workflow](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/projects/projects.controller.ts): `apps/api/src/modules/projects/projects.controller.ts`
- [Project service](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/projects/projects.service.ts): `apps/api/src/modules/projects/projects.service.ts`
- [Sizing engine](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/sizing/default-sizing.engine.ts): `apps/api/src/modules/sizing/default-sizing.engine.ts`
- [Document service](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/documents/documents.service.ts): `apps/api/src/modules/documents/documents.service.ts`

### Tenant administration

- [Company management](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/companies/companies.controller.ts): `apps/api/src/modules/companies/companies.controller.ts`
- [Location management](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/locations/locations.controller.ts): `apps/api/src/modules/locations/locations.controller.ts`
- [User management](https://github.com/ahmedhrgx/pv-sharing/blob/main/apps/api/src/modules/users/users.service.ts): `apps/api/src/modules/users/users.service.ts`

### External services

- **PostgreSQL**
- **Amazon Cognito**
- **HubSpot CRM**
- **Amazon S3**

### Shared domain

- [Contracts and domain](https://github.com/ahmedhrgx/pv-sharing/blob/main/packages/shared/src/contracts.ts): `packages/shared/src/contracts.ts`

### Other components

- **Integrator**

## Connections

- Integrator → Amazon Cognito: signs in
- Integrator → Project workflow: configures project
- Project workflow → Sizing calculator: configures sizing
- Project workflow → Project data room: manages files
- Project workflow → API data source: requests data
- Sizing calculator → API data source: saves configuration
- Project data room → API data source: uploads and retrieves
- Admin portal → API data source: manages tenants
- API data source → REST API: REST requests
- REST API → Token verification: guards routes
- REST API → Project workflow: routes projects
- REST API → Document service: routes documents
- REST API → Company management: routes companies
- REST API → Location management: routes locations
- REST API → User management: routes users
- Project workflow → Project service: invokes
- Project service → PostgreSQL: reads and writes
- Project workflow → Sizing engine: computes sizing
- Project workflow → HubSpot CRM: submits quote
- Document service → Amazon S3: stores documents
- Document service → HubSpot CRM: stores files
- Company management → PostgreSQL: reads and writes
- Location management → PostgreSQL: reads and writes
- User management → PostgreSQL: reads and writes
- Token verification → Amazon Cognito: verifies tokens
- Project workflow → Contracts and domain: uses shared types
- Sizing engine → Contracts and domain: uses sizing types