# rguziy/billcore architecture

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

- Interactive diagram: https://gitdiagram.com/rguziy/billcore
- Repository: https://github.com/rguziy/billcore

## Overview

BillCore is a role-based billing system for utility and telecom operations. Users sign in, manage clients and service locations, configure services and tariffs, maintain subscriptions, and enter or review period calculations; managers and admins also manage periods and view statistics. The Go API routes requests through authorization and feature handlers to business logic and SQL repositories backed by PostgreSQL, while the Next.js frontend provides the corresponding workspaces. The frontend-to-API wiring and several unsampled handler/repository links are not shown, so those connections are omitted or marked unverified.

Main entry points: [`internal/api/router.go`](https://github.com/rguziy/billcore/blob/master/internal/api/router.go) (HTTP router), [`internal/service/period_service.go`](https://github.com/rguziy/billcore/blob/master/internal/service/period_service.go) (Period generation), [`internal/api/handler/calculation_handler.go`](https://github.com/rguziy/billcore/blob/master/internal/api/handler/calculation_handler.go) (Calculation and reports API), [`internal/service/auth_service.go`](https://github.com/rguziy/billcore/blob/master/internal/service/auth_service.go) (Login and language)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workspaces"]
  node_webpages["Billing screens<br/>[page.tsx]"]
  node_clientui["Client workspace<br/>[page.tsx]"]
  node_clientdetail["Client profile<br/>[page.tsx]"]
  node_locationsui["Location workspace<br/>[page.tsx]"]
  node_servicesui["Services tariffs<br/>[page.tsx]"]
  node_subscriptionsui["Subscriptions<br/>[page.tsx]"]
  node_periodsui["Periods<br/>[page.tsx]"]
  node_statisticsui["Statistics<br/>[page.tsx]"]
  node_usersui["User administration<br/>[page.tsx]"]
  node_loginui["Sign in<br/>[page.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
  node_authui["Session handling<br/>[auth.ts]"]
end

subgraph group_api["API and access"]
  node_api_router["HTTP router<br/>[router.go]"]
  node_auth_handler["Authentication<br/>[auth_handler.go]"]
  node_auth_mw["JWT access control<br/>[auth.go]"]
  node_client_handler["Client and location API<br/>[client_handler.go]"]
  node_calc_handler["Calculation and reports API"]
  node_service_handler["Services API<br/>[service_handler.go]"]
  node_subscription_handler["Subscription API"]
  node_user_handler["User administration API<br/>[user_handler.go]"]
  node_period_handler["Period API<br/>[period_handler.go]"]
  node_auth_service["Login and language<br/>[auth_service.go]"]
  node_server["BillCore server<br/>[main.go]"]
end

subgraph group_billing["Billing operations"]
  node_period_service["Period generation<br/>[period_service.go]"]
  node_report_service["Financial reporting<br/>[report_service.go]"]
end

subgraph group_data["Persistence"]
  node_client_repo["Client and location data<br/>[client_repo.go]"]
  node_calc_repo["Calculation data"]
  node_service_repo["Service and tariff data<br/>[service_repo.go]"]
  node_subscription_repo["Subscription data"]
  node_user_repo["User data<br/>[user_repo.go]"]
  node_period_repo["Period data<br/>[period_repo.go]"]
  node_database[("PostgreSQL")]
end

node_operator(("Billing user"))

node_operator -->|"signs in"| node_loginui
node_operator -->|"uses billing UI"| node_webpages
node_operator -->|"manages clients"| node_clientui
node_operator -->|"manages locations"| node_locationsui
node_operator -->|"manages tariffs"| node_servicesui
node_operator -->|"manages subscriptions"| node_subscriptionsui
node_operator -->|"views periods"| node_periodsui
node_operator -->|"reviews statistics"| node_statisticsui
node_operator -->|"administers users"| node_usersui
node_clientui -.->|"opens profile"| node_clientdetail
node_loginui -.->|"uses API"| node_webapi
node_webpages -.->|"uses API"| node_webapi
node_authui -.->|"uses API"| node_webapi
node_server -->|"mounts routes"| node_api_router
node_api_router -->|"routes login"| node_auth_handler
node_api_router -->|"guards routes"| node_auth_mw
node_api_router -->|"routes clients"| node_client_handler
node_api_router -->|"routes calculations"| node_calc_handler
node_api_router -->|"routes services"| node_service_handler
node_api_router -->|"routes subscriptions"| node_subscription_handler
node_api_router -->|"routes periods"| node_period_handler
node_api_router -->|"routes users"| node_user_handler
node_auth_handler -->|"authenticates"| node_auth_service
node_auth_mw -->|"validates token"| node_auth_service
node_auth_service -->|"reads and updates"| node_user_repo
node_client_handler -->|"reads and writes"| node_client_repo
node_calc_handler -->|"reads and writes"| node_calc_repo
node_calc_handler -.->|"requests reports"| node_report_service
node_service_handler -->|"reads and writes"| node_service_repo
node_subscription_handler -->|"reads and writes"| node_subscription_repo
node_user_handler -->|"reads and writes"| node_user_repo
node_period_handler -.->|"delegates period work"| node_period_service
node_period_service -.->|"uses period data"| node_period_repo
node_period_service -.->|"uses tariff data"| node_service_repo
node_period_service -->|"generates calculations"| node_database
node_report_service -->|"queries report views"| node_database
node_client_repo -->|"queries and mutates"| node_database
node_calc_repo -.->|"queries and mutates"| node_database
node_service_repo -->|"queries and mutates"| node_database
node_subscription_repo -.->|"queries and mutates"| node_database
node_user_repo -.->|"queries and mutates"| node_database
node_period_repo -.->|"queries and mutates"| node_database

click node_webpages "https://github.com/rguziy/billcore/blob/master/web/app/calculations/page.tsx"
click node_clientui "https://github.com/rguziy/billcore/blob/master/web/app/clients/page.tsx"
click node_clientdetail "https://github.com/rguziy/billcore/blob/master/web/app/clients/detail/page.tsx"
click node_locationsui "https://github.com/rguziy/billcore/blob/master/web/app/locations/page.tsx"
click node_servicesui "https://github.com/rguziy/billcore/blob/master/web/app/services/page.tsx"
click node_subscriptionsui "https://github.com/rguziy/billcore/blob/master/web/app/subscriptions/page.tsx"
click node_periodsui "https://github.com/rguziy/billcore/blob/master/web/app/periods/page.tsx"
click node_statisticsui "https://github.com/rguziy/billcore/blob/master/web/app/statistics/page.tsx"
click node_usersui "https://github.com/rguziy/billcore/blob/master/web/app/users/page.tsx"
click node_loginui "https://github.com/rguziy/billcore/blob/master/web/app/login/page.tsx"
click node_webapi "https://github.com/rguziy/billcore/blob/master/web/lib/api.ts"
click node_authui "https://github.com/rguziy/billcore/blob/master/web/lib/auth.ts"
click node_api_router "https://github.com/rguziy/billcore/blob/master/internal/api/router.go"
click node_auth_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/auth_handler.go"
click node_auth_mw "https://github.com/rguziy/billcore/blob/master/internal/api/middleware/auth.go"
click node_client_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/client_handler.go"
click node_calc_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/calculation_handler.go"
click node_service_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/service_handler.go"
click node_subscription_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/subscription_handler.go"
click node_user_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/user_handler.go"
click node_period_handler "https://github.com/rguziy/billcore/blob/master/internal/api/handler/period_handler.go"
click node_auth_service "https://github.com/rguziy/billcore/blob/master/internal/service/auth_service.go"
click node_period_service "https://github.com/rguziy/billcore/blob/master/internal/service/period_service.go"
click node_report_service "https://github.com/rguziy/billcore/blob/master/internal/service/report_service.go"
click node_client_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/client_repo.go"
click node_calc_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/calculation_repo.go"
click node_service_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/service_repo.go"
click node_subscription_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/subscription_repo.go"
click node_user_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/user_repo.go"
click node_period_repo "https://github.com/rguziy/billcore/blob/master/internal/repository/period_repo.go"
click node_server "https://github.com/rguziy/billcore/blob/master/cmd/server/main.go"

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_webpages,node_clientui,node_clientdetail,node_locationsui,node_servicesui,node_subscriptionsui,node_periodsui,node_statisticsui,node_usersui,node_loginui,node_webapi,node_authui,node_operator toneBlue
class node_api_router,node_auth_handler,node_auth_mw,node_client_handler,node_calc_handler,node_service_handler,node_subscription_handler,node_user_handler,node_period_handler,node_auth_service,node_server toneAmber
class node_period_service,node_report_service toneMint
class node_client_repo,node_calc_repo,node_service_repo,node_subscription_repo,node_user_repo,node_period_repo,node_database toneRose
```

## Components

### Web workspaces

- [Billing screens](https://github.com/rguziy/billcore/blob/master/web/app/calculations/page.tsx): `web/app/calculations/page.tsx`
- [Client workspace](https://github.com/rguziy/billcore/blob/master/web/app/clients/page.tsx): `web/app/clients/page.tsx`
- [Client profile](https://github.com/rguziy/billcore/blob/master/web/app/clients/detail/page.tsx): `web/app/clients/detail/page.tsx`
- [Location workspace](https://github.com/rguziy/billcore/blob/master/web/app/locations/page.tsx): `web/app/locations/page.tsx`
- [Services tariffs](https://github.com/rguziy/billcore/blob/master/web/app/services/page.tsx): `web/app/services/page.tsx`
- [Subscriptions](https://github.com/rguziy/billcore/blob/master/web/app/subscriptions/page.tsx): `web/app/subscriptions/page.tsx`
- [Periods](https://github.com/rguziy/billcore/blob/master/web/app/periods/page.tsx): `web/app/periods/page.tsx`
- [Statistics](https://github.com/rguziy/billcore/blob/master/web/app/statistics/page.tsx): `web/app/statistics/page.tsx`
- [User administration](https://github.com/rguziy/billcore/blob/master/web/app/users/page.tsx): `web/app/users/page.tsx`
- [Sign in](https://github.com/rguziy/billcore/blob/master/web/app/login/page.tsx): `web/app/login/page.tsx`
- [API client](https://github.com/rguziy/billcore/blob/master/web/lib/api.ts): `web/lib/api.ts`
- [Session handling](https://github.com/rguziy/billcore/blob/master/web/lib/auth.ts): `web/lib/auth.ts`

### API and access

- [HTTP router](https://github.com/rguziy/billcore/blob/master/internal/api/router.go): `internal/api/router.go`
- [Authentication](https://github.com/rguziy/billcore/blob/master/internal/api/handler/auth_handler.go): `internal/api/handler/auth_handler.go`
- [JWT access control](https://github.com/rguziy/billcore/blob/master/internal/api/middleware/auth.go): `internal/api/middleware/auth.go`
- [Client and location API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/client_handler.go): `internal/api/handler/client_handler.go`
- [Calculation and reports API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/calculation_handler.go): `internal/api/handler/calculation_handler.go`
- [Services API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/service_handler.go): `internal/api/handler/service_handler.go`
- [Subscription API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/subscription_handler.go): `internal/api/handler/subscription_handler.go`
- [User administration API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/user_handler.go): `internal/api/handler/user_handler.go`
- [Period API](https://github.com/rguziy/billcore/blob/master/internal/api/handler/period_handler.go): `internal/api/handler/period_handler.go`
- [Login and language](https://github.com/rguziy/billcore/blob/master/internal/service/auth_service.go): `internal/service/auth_service.go`
- [BillCore server](https://github.com/rguziy/billcore/blob/master/cmd/server/main.go): `cmd/server/main.go`

### Billing operations

- [Period generation](https://github.com/rguziy/billcore/blob/master/internal/service/period_service.go): `internal/service/period_service.go`
- [Financial reporting](https://github.com/rguziy/billcore/blob/master/internal/service/report_service.go): `internal/service/report_service.go`

### Persistence

- [Client and location data](https://github.com/rguziy/billcore/blob/master/internal/repository/client_repo.go): `internal/repository/client_repo.go`
- [Calculation data](https://github.com/rguziy/billcore/blob/master/internal/repository/calculation_repo.go): `internal/repository/calculation_repo.go`
- [Service and tariff data](https://github.com/rguziy/billcore/blob/master/internal/repository/service_repo.go): `internal/repository/service_repo.go`
- [Subscription data](https://github.com/rguziy/billcore/blob/master/internal/repository/subscription_repo.go): `internal/repository/subscription_repo.go`
- [User data](https://github.com/rguziy/billcore/blob/master/internal/repository/user_repo.go): `internal/repository/user_repo.go`
- [Period data](https://github.com/rguziy/billcore/blob/master/internal/repository/period_repo.go): `internal/repository/period_repo.go`
- **PostgreSQL**

### Other components

- **Billing user**

## Connections

- Billing user → Sign in: signs in (evidence: `README.md`)
- Billing user → Billing screens: uses billing UI (evidence: `README.md`)
- Billing user → Client workspace: manages clients (evidence: `README.md`)
- Billing user → Location workspace: manages locations (evidence: `README.md`)
- Billing user → Services tariffs: manages tariffs (evidence: `README.md`)
- Billing user → Subscriptions: manages subscriptions (evidence: `README.md`)
- Billing user → Periods: views periods (evidence: `README.md`)
- Billing user → Statistics: reviews statistics (evidence: `README.md`)
- Billing user → User administration: administers users (evidence: `README.md`)
- Client workspace → Client profile: opens profile
- Sign in → API client: uses API
- Billing screens → API client: uses API
- Session handling → API client: uses API
- BillCore server → HTTP router: mounts routes (evidence: `cmd/server/main.go`)
- HTTP router → Authentication: routes login (evidence: `internal/api/router.go`)
- HTTP router → JWT access control: guards routes (evidence: `internal/api/router.go`)
- HTTP router → Client and location API: routes clients (evidence: `internal/api/router.go`)
- HTTP router → Calculation and reports API: routes calculations (evidence: `internal/api/router.go`)
- HTTP router → Services API: routes services (evidence: `internal/api/router.go`)
- HTTP router → Subscription API: routes subscriptions (evidence: `internal/api/router.go`)
- HTTP router → Period API: routes periods (evidence: `internal/api/router.go`)
- HTTP router → User administration API: routes users (evidence: `internal/api/router.go`)
- Authentication → Login and language: authenticates (evidence: `internal/api/handler/auth_handler.go`)
- JWT access control → Login and language: validates token (evidence: `internal/api/middleware/auth.go`)
- Login and language → User data: reads and updates (evidence: `internal/service/auth_service.go`)
- Client and location API → Client and location data: reads and writes (evidence: `internal/api/handler/client_handler.go`)
- Calculation and reports API → Calculation data: reads and writes (evidence: `internal/api/handler/calculation_handler.go`)
- Calculation and reports API → Financial reporting: requests reports
- Services API → Service and tariff data: reads and writes (evidence: `internal/api/handler/service_handler.go`)
- Subscription API → Subscription data: reads and writes (evidence: `internal/api/handler/subscription_handler.go`)
- User administration API → User data: reads and writes (evidence: `internal/api/handler/user_handler.go`)
- Period API → Period generation: delegates period work
- Period generation → Period data: uses period data
- Period generation → Service and tariff data: uses tariff data
- Period generation → PostgreSQL: generates calculations (evidence: `internal/service/period_service.go`)
- Financial reporting → PostgreSQL: queries report views (evidence: `internal/service/report_service.go`)
- Client and location data → PostgreSQL: queries and mutates (evidence: `internal/repository/client_repo.go`)
- Calculation data → PostgreSQL: queries and mutates
- Service and tariff data → PostgreSQL: queries and mutates (evidence: `internal/repository/service_repo.go`)
- Subscription data → PostgreSQL: queries and mutates
- User data → PostgreSQL: queries and mutates
- Period data → PostgreSQL: queries and mutates
