# codebangla/invoicika architecture

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

- Interactive diagram: https://gitdiagram.com/codebangla/invoicika
- Repository: https://github.com/codebangla/invoicika

## Overview

#### Purpose and Runtime
Invoicika is a full-stack invoice-management system: Angular 16 browser client, ASP.NET Core Web API 10 backend, and PostgreSQL persistence. It supports authentication/roles, customers, catalog items and groups, VAT, and invoice lifecycle operations including PDF/email capabilities. Docker orchestration is provided by `docker-compose.yml`; independent images are defined in `Frontend/Dockerfile` and `WebAPI/Dockerfile`.

#### Application Entry Points
The Angular bootstrap is `Frontend/src/main.ts`, which loads the root module at `Frontend/src/app/app.module.ts`; global navigation begins in `Frontend/src/app/app-routing.module.ts`. The API host and dependency pipeline begin at `WebAPI/Program.cs`. Runtime configuration and connection/service settings reside in `WebAPI/appsettings.json` and `WebAPI/appsettings.Development.json`.

#### Frontend Shell, Navigation, and Security
The root component supplies the application shell in `Frontend/src/app/app.component.ts`. Feature areas are independently routed Angular modules, allowing navigation among login/signup, dashboard, and domain management pages. Route protection is enforced by `Frontend/src/app/guards/auth.guard.ts`; outbound API calls cross `Frontend/src/app/interceptors/auth.interceptor.ts`, the main client-side authentication boundary. Authentication state is centralized under `Frontend/src/app/states/auth/auth.state.ts`, while API login/session operations are in `Frontend/src/app/services/auth.service.ts`.

#### Frontend Domain Workflows
CRUD-oriented feature modules represent the user-facing business flows: customers (`Frontend/src/app/pages/customer/customer.module.ts`), invoices (`Frontend/src/app/pages/invoice/invoice.module.ts`), item groups (`Frontend/src/app/pages/group/group.module.ts`), plus items, VAT, users, and roles. Invoice creation, edit, display, and list screens form the central workflow, notably `Frontend/src/app/pages/invoice/invoice-add/invoice-add.component.ts`, `Frontend/src/app/pages/invoice/invoice-show/invoice-show.component.ts`, and `Frontend/src/app/services/customerinvoice.service.ts`. NG-Zorro integration is consolidated in `Frontend/src/app/modules/ng-zorro/ng-zorro.module.ts`.

#### HTTP API and Business Layer
Controllers expose resource-specific API endpoints and delegate domain behavior to services: authentication through `WebAPI/Controllers/AuthController.cs` and `WebAPI/Services/AuthService.cs`; invoices through `WebAPI/Controllers/CustomerInvoicesController.cs` and `WebAPI/Services/CustomerInvoiceService.cs`; customers through `WebAPI/Controllers/CustomersController.cs` and `WebAPI/Services/CustomerService.cs`. This controller-to-service boundary separates HTTP concerns from business and persistence operations. DTOs define transport shapes where present, including `WebAPI/Dtos/AuthDto.cs` and `WebAPI/Dtos/CustomerInvoiceDto.cs`.

#### Invoice Domain and Persistence
Entity Framework Core persists the relational invoice model through `WebAPI/Data/InvocikaDbContext.cs` to PostgreSQL. The aggregate spans invoice headers, status, direct item lines, grouped-item lines, customers, items, groups, and VAT; core representations are `WebAPI/Models/CustomerInvoice.cs`, `WebAPI/Models/CustomerInvoiceLine.cs`, and `WebAPI/Models/CustomerInvoiceGroupLine.cs`. Schema evolution is code-first via `WebAPI/Migrations/20251223191043_Initial.cs`; startup seed behavior is represented by `WebAPI/Data/SeedData.cs`.

#### External Boundaries and Delivery
The browser communicates with the ASP.NET API using environment-specific frontend configuration in `Frontend/src/environments/environment.ts`. The backend owns database access and exposes uploaded static content beneath `WebAPI/wwwroot/uploads`. PostgreSQL is the required durable store; SMTP configuration in backend settings enables email delivery, and the documented backend endpoint exposes Swagger for API inspection. Containerized deployment links frontend, backend, and database through `docker-compose.yml`.

Main entry points: [`Frontend/src/app/app-routing.module.ts`](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/app-routing.module.ts) (Application routing), [`WebAPI/Services/CustomerInvoiceService.cs`](https://github.com/codebangla/invoicika/blob/main/WebAPI/Services/CustomerInvoiceService.cs) (Domain services), [`Frontend/src/app/guards/auth.guard.ts`](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/guards/auth.guard.ts) (Auth state, guard & interceptor), [`docker-compose.yml`](https://github.com/codebangla/invoicika/blob/main/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular client"]
  node_ng_bootstrap["Angular bootstrap<br/>entry point<br/>[main.ts]"]
  node_ng_app_module["Root module &amp; shell<br/>Angular module<br/>[app.module.ts]"]
  node_ng_routing["Application routing<br/>route registry"]
  node_ng_auth_boundary["Auth state, guard &amp; interceptor<br/>client security boundary<br/>[auth.guard.ts]"]
  node_ng_auth_service["Auth API client<br/>Angular service<br/>[auth.service.ts]"]
  node_ng_invoice_workflow["Invoice workflow<br/>feature module and screens<br/>[invoice.module.ts]"]
  node_ng_customer_workflow["Customer management<br/>feature module<br/>[customer.module.ts]"]
  node_ng_api_config["API environment config<br/>frontend configuration<br/>[environment.ts]"]
end

subgraph group_api["ASP.NET Core API"]
  node_api_host["API host &amp; pipeline<br/>ASP.NET entry point<br/>[Program.cs]"]
  node_api_controllers["Resource controllers<br/>HTTP API layer"]
  node_api_services["Domain services<br/>business layer"]
  node_api_dtos["API DTOs<br/>transport contracts"]
  node_uploads["Uploaded static content<br/>file storage"]
end

subgraph group_data["Persistence"]
  node_db_context["Invoice DbContext<br/>EF Core data access"]
  node_invoice_models["Invoice aggregate<br/>EF Core models<br/>[CustomerInvoice.cs]"]
  node_migrations_seed["Schema migrations &amp; seed<br/>database initialization"]
end

subgraph group_delivery["Deployment &amp; externals"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_smtp["SMTP delivery<br/>external email service"]
  node_compose["Docker Compose<br/>container orchestration<br/>[docker-compose.yml]"]
end

node_ng_bootstrap -->|"boots"| node_ng_app_module
node_ng_app_module -->|"loads routes"| node_ng_routing
node_ng_routing -->|"protects routes"| node_ng_auth_boundary
node_ng_auth_boundary -->|"session operations"| node_ng_auth_service
node_ng_routing -->|"navigates"| node_ng_invoice_workflow
node_ng_routing -->|"navigates"| node_ng_customer_workflow
node_ng_invoice_workflow -->|"authenticated requests"| node_ng_auth_boundary
node_ng_auth_boundary -->|"API base URL"| node_ng_api_config
node_ng_api_config -->|"HTTPS API calls"| node_api_host
node_api_host -->|"maps endpoints"| node_api_controllers
node_api_controllers -->|"uses contracts"| node_api_dtos
node_api_controllers -->|"delegates"| node_api_services
node_api_services -->|"reads and writes"| node_db_context
node_db_context -->|"maps aggregate"| node_invoice_models
node_db_context -->|"EF Core persistence"| node_postgres
node_migrations_seed -->|"initializes schema"| node_postgres
node_api_services -->|"serves upload-related content"| node_uploads
node_api_services -->|"sends invoice email"| node_smtp
node_compose -.->|"runs frontend image"| node_ng_bootstrap
node_compose -.->|"runs API image"| node_api_host
node_compose -.->|"runs database"| node_postgres

click node_ng_bootstrap "https://github.com/codebangla/invoicika/blob/main/Frontend/src/main.ts"
click node_ng_app_module "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/app.module.ts"
click node_ng_routing "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/app-routing.module.ts"
click node_ng_auth_boundary "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/guards/auth.guard.ts"
click node_ng_auth_service "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/services/auth.service.ts"
click node_ng_invoice_workflow "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/pages/invoice/invoice.module.ts"
click node_ng_customer_workflow "https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/pages/customer/customer.module.ts"
click node_ng_api_config "https://github.com/codebangla/invoicika/blob/main/Frontend/src/environments/environment.ts"
click node_api_host "https://github.com/codebangla/invoicika/blob/main/WebAPI/Program.cs"
click node_api_controllers "https://github.com/codebangla/invoicika/blob/main/WebAPI/Controllers/CustomerInvoicesController.cs"
click node_api_services "https://github.com/codebangla/invoicika/blob/main/WebAPI/Services/CustomerInvoiceService.cs"
click node_api_dtos "https://github.com/codebangla/invoicika/blob/main/WebAPI/Dtos/CustomerInvoiceDto.cs"
click node_uploads "https://github.com/codebangla/invoicika/tree/main/WebAPI/wwwroot/uploads"
click node_db_context "https://github.com/codebangla/invoicika/blob/main/WebAPI/Data/InvocikaDbContext.cs"
click node_invoice_models "https://github.com/codebangla/invoicika/blob/main/WebAPI/Models/CustomerInvoice.cs"
click node_migrations_seed "https://github.com/codebangla/invoicika/blob/main/WebAPI/Migrations/20251223191043_Initial.cs"
click node_compose "https://github.com/codebangla/invoicika/blob/main/docker-compose.yml"

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_ng_bootstrap,node_ng_app_module,node_ng_routing,node_ng_auth_boundary,node_ng_auth_service,node_ng_invoice_workflow,node_ng_customer_workflow,node_ng_api_config toneBlue
class node_api_host,node_api_controllers,node_api_services,node_api_dtos,node_uploads toneAmber
class node_db_context,node_invoice_models,node_migrations_seed toneMint
class node_postgres,node_smtp,node_compose toneRose
```

## Components

### Angular client

- [Angular bootstrap](https://github.com/codebangla/invoicika/blob/main/Frontend/src/main.ts): entry point · `Frontend/src/main.ts`
- [Root module & shell](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/app.module.ts): Angular module · `Frontend/src/app/app.module.ts`
- [Application routing](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/app-routing.module.ts): route registry · `Frontend/src/app/app-routing.module.ts`
- [Auth state, guard & interceptor](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/guards/auth.guard.ts): client security boundary · Maintains session state, protects routes, and attaches auth to API requests. · `Frontend/src/app/guards/auth.guard.ts`
- [Auth API client](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/services/auth.service.ts): Angular service · `Frontend/src/app/services/auth.service.ts`
- [Invoice workflow](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/pages/invoice/invoice.module.ts): feature module and screens · Invoice add, display, and list flows use the invoice client service. · `Frontend/src/app/pages/invoice/invoice.module.ts`
- [Customer management](https://github.com/codebangla/invoicika/blob/main/Frontend/src/app/pages/customer/customer.module.ts): feature module · `Frontend/src/app/pages/customer/customer.module.ts`
- [API environment config](https://github.com/codebangla/invoicika/blob/main/Frontend/src/environments/environment.ts): frontend configuration · `Frontend/src/environments/environment.ts`

### ASP.NET Core API

- [API host & pipeline](https://github.com/codebangla/invoicika/blob/main/WebAPI/Program.cs): ASP.NET entry point · Configures dependency injection, middleware, and HTTP endpoints. · `WebAPI/Program.cs`
- [Resource controllers](https://github.com/codebangla/invoicika/blob/main/WebAPI/Controllers/CustomerInvoicesController.cs): HTTP API layer · Auth, invoice, and customer controllers expose resource endpoints. · `WebAPI/Controllers/CustomerInvoicesController.cs`
- [Domain services](https://github.com/codebangla/invoicika/blob/main/WebAPI/Services/CustomerInvoiceService.cs): business layer · Authentication, invoice, and customer behavior is separated from controllers. · `WebAPI/Services/CustomerInvoiceService.cs`
- [API DTOs](https://github.com/codebangla/invoicika/blob/main/WebAPI/Dtos/CustomerInvoiceDto.cs): transport contracts · `WebAPI/Dtos/CustomerInvoiceDto.cs`
- [Uploaded static content](https://github.com/codebangla/invoicika/tree/main/WebAPI/wwwroot/uploads): file storage · `WebAPI/wwwroot/uploads`

### Persistence

- [Invoice DbContext](https://github.com/codebangla/invoicika/blob/main/WebAPI/Data/InvocikaDbContext.cs): EF Core data access · Persists the invoice aggregate and related customer, catalog, group, and VAT data. · `WebAPI/Data/InvocikaDbContext.cs`
- [Invoice aggregate](https://github.com/codebangla/invoicika/blob/main/WebAPI/Models/CustomerInvoice.cs): EF Core models · Invoice headers include direct-item and grouped-item lines. · `WebAPI/Models/CustomerInvoice.cs`
- [Schema migrations & seed](https://github.com/codebangla/invoicika/blob/main/WebAPI/Migrations/20251223191043_Initial.cs): database initialization · `WebAPI/Migrations/20251223191043_Initial.cs`

### Deployment & externals

- **PostgreSQL**: relational database · Durable application store.
- **SMTP delivery**: external email service
- [Docker Compose](https://github.com/codebangla/invoicika/blob/main/docker-compose.yml): container orchestration · Connects frontend, API, and database containers. · `docker-compose.yml`

## Connections

- Angular bootstrap → Root module & shell: boots
- Root module & shell → Application routing: loads routes
- Application routing → Auth state, guard & interceptor: protects routes
- Auth state, guard & interceptor → Auth API client: session operations
- Application routing → Invoice workflow: navigates
- Application routing → Customer management: navigates
- Invoice workflow → Auth state, guard & interceptor: authenticated requests
- Auth state, guard & interceptor → API environment config: API base URL
- API environment config → API host & pipeline: HTTPS API calls
- API host & pipeline → Resource controllers: maps endpoints
- Resource controllers → API DTOs: uses contracts
- Resource controllers → Domain services: delegates
- Domain services → Invoice DbContext: reads and writes
- Invoice DbContext → Invoice aggregate: maps aggregate
- Invoice DbContext → PostgreSQL: EF Core persistence
- Schema migrations & seed → PostgreSQL: initializes schema
- Domain services → Uploaded static content: serves upload-related content
- Domain services → SMTP delivery: sends invoice email
- Docker Compose → Angular bootstrap: runs frontend image
- Docker Compose → API host & pipeline: runs API image
- Docker Compose → PostgreSQL: runs database