# f4cio/world architecture

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

- Interactive diagram: https://gitdiagram.com/f4cio/world
- Repository: https://github.com/f4cio/world

## Overview

#### Purpose and Entry Points
InfoCompass.World is a layered application skeleton for a production-style web system, demonstrated by BookSynth. It provides Angular screens, an ASP.NET Core Web API, user/account flows, city management, logging, and file-system-backed persistence. Server startup is `InfoCompass.World.UiWebApi/Program.cs`; browser startup is `InfoCompass.World.UiAngular/src/main.ts`. The solution root is `InfoCompass.World.sln`.

#### Client Application
The Angular application is organized as routed feature modules with a shared shell and centralized core services. `InfoCompass.World.UiAngular/src/app/app.module.ts` and `InfoCompass.World.UiAngular/src/app/app-routing.module.ts` assemble the application. Account/auth flows live under `InfoCompass.World.UiAngular/src/app/features/auth/` and `InfoCompass.World.UiAngular/src/app/features/account/`; the dashboard/library provide primary authenticated UI areas. HTTP authentication and loading behavior are boundary concerns handled by `InfoCompass.World.UiAngular/src/app/core/interceptors/auth.interceptor.ts` and `InfoCompass.World.UiAngular/src/app/core/interceptors/spinner.interceptor.ts`.

#### API Boundary and Request Handling
The ASP.NET Core API exposes controllers and translates application responses to UI-oriented response models. Main endpoint surfaces are `InfoCompass.World.UiWebApi/Controllers/UsersController.cs`, `InfoCompass.World.UiWebApi/Controllers/CitiesController.cs`, and `InfoCompass.World.UiWebApi/Controllers/Endpoints1.cs`. Authentication logic is separated in `InfoCompass.World.UiWebApi/Logic/HandlerForAuthentication.cs`; request logging context is injected through `InfoCompass.World.UiWebApi/Middleware/SerilogUserContextMiddleware.cs`. The generated client contract is consumed by the frontend at `InfoCompass.World.UiAngular/src/app/shared/api-client.generated.ts`.

#### Business-Layer Composition
Business services implement use cases and coordinate persistence, settings, authentication, email, and logging. Dependency composition is centered at `InfoCompass.World.BusinessLogic/CompositionRoot.cs`. Key services include `InfoCompass.World.BusinessLogic/ServiceForUsers.cs`, `InfoCompass.World.BusinessLogic/ServiceForJwts.cs`, and `InfoCompass.World.BusinessLogic/ServiceForEMails.cs`. This layer is the principal boundary between HTTP concerns and data-access implementations.

#### Shared Domain Contracts
`InfoCompass.World.Common` carries cross-layer entities, request/response models, errors, configuration, and shared validation. Important domain records include `InfoCompass.World.Common/Entities/IEntity/User.cs`, `InfoCompass.World.Common/Entities/IEntity/Jwt.cs`, and `InfoCompass.World.Common/Entities/ServerRequestModels.cs`. These types allow the API, business layer, and persistence implementations to communicate without UI-specific dependencies.

#### Persistence and Operational Data
Persistence is abstracted behind interfaces in `InfoCompass.World.DataAccessContracts/`, including `IServiceForUsers.cs`, `IServiceForJwts.cs`, and `IServiceForLogs.cs`. The supplied implementation stores entities through the file system, composed in `InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs` and implemented by services such as `ServiceForUsers.cs` and `ServiceForEntities.cs`. This makes data storage replaceable at the business-layer boundary.

#### Infrastructure and External Services
The runtime stack is .NET/ASP.NET Core plus Angular/Node.js. Application configuration and SMTP credentials are held in `InfoCompass.World.BusinessLogic/Data/Settings.json`; SMTP is required for registration and password reset flows. JWT issuance supports authenticated requests, while logging has file-per-user/job and database-oriented service variants in `InfoCompass.World.BusinessLogic/ServiceForLogSink_FilePerUserPerJob.cs` and `InfoCompass.World.BusinessLogic/ServiceForLogSink_Db.cs`. `CraftSynth.BuildingBlocks.Generated/` is a shared generated utility library supplying HTTP, serialization, logging, encryption, and I/O primitives.

Main entry points: [`InfoCompass.World.BusinessLogic/ServiceForUsers.cs`](https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/ServiceForUsers.cs) (User, JWT and email services), [`InfoCompass.World.UiWebApi/Program.cs`](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Program.cs) (API host), [`InfoCompass.World.UiWebApi/Controllers/UsersController.cs`](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Controllers/UsersController.cs) (Users, cities and endpoints), [`InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs`](https://github.com/f4cio/world/blob/main/InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs) (File-system composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Angular client"]
  node_angular_bootstrap["Angular bootstrap<br/>browser entry<br/>[main.ts]"]
  node_angular_app["App shell and routing<br/>Angular modules<br/>[app.module.ts]"]
  node_angular_features["Auth, account and library UI<br/>Angular features"]
  node_angular_interceptors["HTTP auth and spinner<br/>Angular interceptors"]
  node_generated_client["Generated API client<br/>client contract"]
end

subgraph group_api["ASP.NET Core API"]
  node_api_host["API host<br/>ASP.NET Core entry<br/>[Program.cs]"]
  node_api_controllers["Users, cities and endpoints<br/>API controllers<br/>[UsersController.cs]"]
  node_api_auth["Authentication handler<br/>API auth"]
  node_api_logging["User logging context<br/>API middleware"]
end

subgraph group_core["Application core"]
  node_business_composition{{"Business composition<br/>DI composition<br/>[CompositionRoot.cs]"}}
  node_business_services["User, JWT and email services<br/>use cases<br/>[ServiceForUsers.cs]"]
  node_domain_contracts["Domain contracts<br/>shared models"]
  node_settings["Application settings<br/>settings data<br/>[Settings.json]"]
  node_log_sinks["Log sinks<br/>operational logging"]
end

subgraph group_data["Persistence"]
  node_data_contracts{{"Data access interfaces<br/>persistence ports"}}
  node_filesystem_composition["File-system composition<br/>storage DI<br/>[CompositionRoot.cs]"]
  node_filesystem_services["File-system entity services<br/>storage adapter"]
end

node_smtp["SMTP service<br/>external email"]
node_generated_building_blocks["Generated building blocks<br/>shared utility library"]

node_angular_bootstrap -->|"starts"| node_angular_app
node_angular_app -->|"routes to"| node_angular_features
node_angular_features -->|"uses HTTP pipeline"| node_angular_interceptors
node_angular_interceptors -->|"wraps requests"| node_generated_client
node_generated_client -->|"calls"| node_api_controllers
node_api_host -->|"installs"| node_api_logging
node_api_host -->|"configures"| node_api_auth
node_api_host -->|"hosts"| node_api_controllers
node_api_controllers -->|"invokes"| node_business_services
node_api_auth -->|"validates through"| node_business_services
node_business_composition -->|"wires"| node_business_services
node_business_services -->|"uses"| node_domain_contracts
node_business_services -->|"depends on"| node_data_contracts
node_business_services -->|"reads"| node_settings
node_business_services -->|"sends email via"| node_smtp
node_business_services -->|"emits logs to"| node_log_sinks
node_filesystem_composition -->|"implements"| node_data_contracts
node_filesystem_composition -->|"wires"| node_filesystem_services
node_filesystem_services -->|"stores entities"| node_domain_contracts
node_api_host -.->|"uses utilities"| node_generated_building_blocks
node_business_services -.->|"uses utilities"| node_generated_building_blocks

click node_angular_bootstrap "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/main.ts"
click node_angular_app "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/app.module.ts"
click node_angular_interceptors "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/core/interceptors/auth.interceptor.ts"
click node_generated_client "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/shared/api-client.generated.ts"
click node_api_host "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Program.cs"
click node_api_controllers "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Controllers/UsersController.cs"
click node_api_auth "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Logic/HandlerForAuthentication.cs"
click node_api_logging "https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Middleware/SerilogUserContextMiddleware.cs"
click node_business_composition "https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/CompositionRoot.cs"
click node_business_services "https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/ServiceForUsers.cs"
click node_domain_contracts "https://github.com/f4cio/world/blob/main/InfoCompass.World.Common/Entities/ServerRequestModels.cs"
click node_settings "https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/Data/Settings.json"
click node_log_sinks "https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/ServiceForLogSink_FilePerUserPerJob.cs"
click node_filesystem_composition "https://github.com/f4cio/world/blob/main/InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs"
click node_filesystem_services "https://github.com/f4cio/world/blob/main/InfoCompass.World.DataAccessByFileSystem/ServiceForEntities.cs"

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_angular_bootstrap,node_angular_app,node_angular_features,node_angular_interceptors,node_generated_client toneBlue
class node_api_host,node_api_controllers,node_api_auth,node_api_logging toneAmber
class node_business_composition,node_business_services,node_domain_contracts,node_settings,node_log_sinks toneMint
class node_data_contracts,node_filesystem_composition,node_filesystem_services toneRose
class node_smtp,node_generated_building_blocks toneNeutral
```

## Components

### Angular client

- [Angular bootstrap](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/main.ts): browser entry · `InfoCompass.World.UiAngular/src/main.ts`
- [App shell and routing](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/app.module.ts): Angular modules · Assembles routed feature modules. · `InfoCompass.World.UiAngular/src/app/app.module.ts`
- **Auth, account and library UI**: Angular features · Primary public and authenticated screens.
- [HTTP auth and spinner](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/core/interceptors/auth.interceptor.ts): Angular interceptors · `InfoCompass.World.UiAngular/src/app/core/interceptors/auth.interceptor.ts`
- [Generated API client](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiAngular/src/app/shared/api-client.generated.ts): client contract · `InfoCompass.World.UiAngular/src/app/shared/api-client.generated.ts`

### ASP.NET Core API

- [API host](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Program.cs): ASP.NET Core entry · `InfoCompass.World.UiWebApi/Program.cs`
- [Users, cities and endpoints](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Controllers/UsersController.cs): API controllers · Maps HTTP requests to UI response models. · `InfoCompass.World.UiWebApi/Controllers/UsersController.cs`
- [Authentication handler](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Logic/HandlerForAuthentication.cs): API auth · `InfoCompass.World.UiWebApi/Logic/HandlerForAuthentication.cs`
- [User logging context](https://github.com/f4cio/world/blob/main/InfoCompass.World.UiWebApi/Middleware/SerilogUserContextMiddleware.cs): API middleware · `InfoCompass.World.UiWebApi/Middleware/SerilogUserContextMiddleware.cs`

### Application core

- [Business composition](https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/CompositionRoot.cs): DI composition · Wires use cases to replaceable infrastructure. · `InfoCompass.World.BusinessLogic/CompositionRoot.cs`
- [User, JWT and email services](https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/ServiceForUsers.cs): use cases · Coordinates accounts, authentication, settings, email and storage. · `InfoCompass.World.BusinessLogic/ServiceForUsers.cs`
- [Domain contracts](https://github.com/f4cio/world/blob/main/InfoCompass.World.Common/Entities/ServerRequestModels.cs): shared models · Entities, request/response models, errors and validation. · `InfoCompass.World.Common/Entities/ServerRequestModels.cs`
- [Application settings](https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/Data/Settings.json): settings data · Includes SMTP configuration. · `InfoCompass.World.BusinessLogic/Data/Settings.json`
- [Log sinks](https://github.com/f4cio/world/blob/main/InfoCompass.World.BusinessLogic/ServiceForLogSink_FilePerUserPerJob.cs): operational logging · Supports file-per-user/job and database variants. · `InfoCompass.World.BusinessLogic/ServiceForLogSink_FilePerUserPerJob.cs`

### Persistence

- **Data access interfaces**: persistence ports · Abstracts users, JWTs and logs storage.
- [File-system composition](https://github.com/f4cio/world/blob/main/InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs): storage DI · `InfoCompass.World.DataAccessByFileSystem/CompositionRoot.cs`
- [File-system entity services](https://github.com/f4cio/world/blob/main/InfoCompass.World.DataAccessByFileSystem/ServiceForEntities.cs): storage adapter · `InfoCompass.World.DataAccessByFileSystem/ServiceForEntities.cs`

### Other components

- **SMTP service**: external email · Used for registration and password reset.
- **Generated building blocks**: shared utility library · Provides HTTP, serialization, logging, encryption and I/O primitives.

## Connections

- Angular bootstrap → App shell and routing: starts
- App shell and routing → Auth, account and library UI: routes to
- Auth, account and library UI → HTTP auth and spinner: uses HTTP pipeline
- HTTP auth and spinner → Generated API client: wraps requests
- Generated API client → Users, cities and endpoints: calls
- API host → User logging context: installs
- API host → Authentication handler: configures
- API host → Users, cities and endpoints: hosts
- Users, cities and endpoints → User, JWT and email services: invokes
- Authentication handler → User, JWT and email services: validates through
- Business composition → User, JWT and email services: wires
- User, JWT and email services → Domain contracts: uses
- User, JWT and email services → Data access interfaces: depends on
- User, JWT and email services → Application settings: reads
- User, JWT and email services → SMTP service: sends email via
- User, JWT and email services → Log sinks: emits logs to
- File-system composition → Data access interfaces: implements
- File-system composition → File-system entity services: wires
- File-system entity services → Domain contracts: stores entities
- API host → Generated building blocks: uses utilities
- User, JWT and email services → Generated building blocks: uses utilities