Project Structure

A detailed breakdown of every top-level directory and its contents.

Root Layout

unpispas.nx/
├── apps/               # Angular applications
├── libs/               # Shared libraries (general + feature)
├── server/             # PHP REST API backend
├── docker/             # Docker Compose deployment & dev environment
├── docs/               # Generated documentation (codedoc, coverage, swagger)
├── dist/               # Build output (gitignored)
├── nx.json             # Nx workspace configuration
├── package.json        # Root npm dependencies
└── tsconfig.base.json  # Shared TypeScript configuration

apps/ — Angular Applications

apps/unpispas-pos/

The main production application — a Point of Sale (POS) system built with Angular and Ionic.

apps/unpispas-pos/
├── src/
│   ├── app/
│   │   ├── app.module.ts        # Root module — imports UppBaseModule, UppWdgtModule, features
│   │   ├── app.component.ts     # Root component
│   │   ├── app.component.main.ts # Main shell component
│   │   └── app.routes.ts        # Route definitions
│   ├── main.ts                  # Application bootstrap
│   ├── index.html               # Entry HTML
│   └── styles.scss              # Global styles
├── public/                      # Static assets (favicon, etc.)
├── project.json                 # Nx project config (build, serve, test, lint targets)
├── tsconfig.app.json            # App-specific TypeScript config
└── jest.config.ts               # Test configuration

Key project.json settings:

• Build executor: @angular-devkit/build-angular:browser-esbuild
• Output: dist/apps/unpispas-pos
• Base href: /unpispas-pos/
• Explicit build dependencies: upp-data, upp-wdgt, and all imported feature libraries

apps/upp-test/

For tests, documentation, and examples. Used for demos, experimentation, and reference implementations. Not part of the production product.

apps/upp-guide/

The Docusaurus documentation site (this site). Contains developer guides, architecture docs, and API references.

libs/ — Shared Libraries

Libraries are split into two groups: general-purpose and feature.

General-Purpose Libraries

libs/upp-defs/

Foundation layer. Pure constants and utilities with no Angular service dependencies.

libs/upp-defs/src/
├── index.ts             # Public API: AppConstants, GenericUtils
├── app.constants.ts     # Application-wide constants (URLs, timeouts, etc.)
├── app.utils.ts         # Pure utility functions (hashing, date formatting, UUID)
└── lib/
    └── upp-defs.component.ts

libs/upp-base/

Infrastructure services. Depends on upp-defs.

libs/upp-base/src/
├── index.ts             # Public API (re-exports all modules)
├── lib/
│   └── upp-base.module.ts   # UppBaseModule (Ionic, Storage, HTTP, Cordova plugins)
└── modules/
    ├── state.ts         # stateService — session, device, access mode
    ├── view.ts          # viewService — current view, edit mode, panels, theme
    ├── events.ts        # eventbusService — global pub/sub event bus
    ├── http.ts          # httpService — HTTP client, online/offline
    ├── socket.ts        # socketService — WebSocket abstraction
    ├── adhoc.ts         # adhocService — typed API requests
    ├── clock.ts         # clockService — periodic tick for deferred refresh
    ├── store.ts         # storeService — Ionic Storage wrapper
    ├── language.ts      # languageService — i18n
    ├── localcfg.ts      # configService — local configuration persistence
    ├── logs.ts          # Logging utilities
    ├── alert.ts         # alertService — modal alerts and input dialogs
    ├── toasts.ts        # toastService — toast notifications
    ├── device.ts        # identificationService — device UUID
    ├── platform.ts      # platformService — device type, browser, theme
    ├── kiosk.ts         # Kiosk mode keyboard component
    ├── upload.ts        # uploadService — file uploads
    ├── geocode.ts       # Geolocation and away-detection
    └── preload.ts       # Asset preloading

libs/upp-data/

Data model and synchronization engine. Depends on upp-base.

libs/upp-data/src/
├── index.ts             # Public API (model objects, views, services)
├── lib/
│   └── upp-data.module.ts   # UppDataModule (minimal — services use providedIn: root)
└── modules/
    ├── data.ts          # dataService — central data store, object factory, commit
    ├── sync.ts          # syncService — server connection, long-poll, change queue
    ├── cache.ts         # cacheService — IndexedDB local cache
    ├── login.ts         # loginService — authentication flow
    ├── events.ts        # Event classes (DrawerEvent, LoginEvent, GuestEvent)
    └── model/
        ├── base.ts      # BaseObject → RelatedObject → DataObject → ViewObject
        ├── item.ts      # Schema system, CreateObject, BaseClass, type generation
        ├── factory.ts   # ObjectFactory — creates instances by table name
        ├── objects/     # DataObject subclasses (one per domain entity)
        │   ├── ticket.ts
        │   ├── product.ts
        │   ├── place.ts
        │   ├── user.ts
        │   ├── session.ts
        │   ├── category.ts
        │   ├── employee.ts
        │   ├── offer.ts
        │   ├── extra.ts
        │   ├── discount.ts
        │   ├── qrcode.ts
        │   ├── printer.ts
        │   └── ... (30+ entity types)
        └── views/       # ViewObject subclasses (computed properties, subscriptions)
            ├── ticket.ts
            ├── product.ts
            ├── place.ts
            └── ... (matching view for each object)

libs/upp-wdgt/

Reusable UI components and directives. Depends on upp-base.

libs/upp-wdgt/src/
├── index.ts
├── lib/
│   └── upp-wdgt.module.ts
├── components/
│   ├── upp-application/   # Root app shell
│   ├── upp-panel/         # Panel layout
│   ├── upp-header/        # Header bar
│   ├── upp-grid/          # Data grid
│   ├── upp-scrollable/    # Scrollable container
│   ├── upp-input/         # Text input
│   ├── upp-textarea/      # Multi-line input
│   ├── upp-select/        # Dropdown select
│   ├── upp-dropdown/      # Dropdown menu
│   ├── upp-tabbar/        # Tab bar navigation
│   ├── upp-search/        # Search input with filtering
│   ├── upp-form/          # Form container
│   ├── upp-image/         # Image display
│   ├── upp-thumb/         # Thumbnail
│   ├── upp-crop/          # Image cropping
│   ├── upp-address/       # Address form
│   └── upp-visible/       # Visibility detection
├── directives/
│   ├── upp-dataid.ts      # Data ID attribute directive
│   ├── upp-touch.ts       # Touch event directive
│   └── upp-visible.ts     # Intersection observer directive
└── injectables/
    └── renderer.ts        # Rendering service

Feature Libraries (libs/feature/)

Each feature encapsulates a specific domain area and is consumed by applications.

Directory	Module	Purpose
feature/login/	FeatureLoginModule	Login, registration, password recovery screens
feature/topbar/	FeatureTopbarModule	Application top navigation bar
feature/user/	FeatureUserModule	User profile and account management
feature/place/	FeaturePlaceModule	Place selection, creation, configuration
feature/ticket/	—	Ticket (sale/order) creation and management
feature/product/	—	Product catalog CRUD
feature/category/	—	Category management
feature/offer/	—	Offers and promotions
feature/extra/	—	Extras (add-ons) configuration
feature/employee/	—	Employee/staff management
feature/qrcode/	—	QR code (table) management
feature/shortcut/	—	Quick-access shortcut buttons
feature/period/	—	Time period/schedule management
feature/assets/	—	Shared static assets (images, icons)

server/ — PHP Backend

The REST API backend, currently being migrated from classic PHP scripts to the Slim framework.

server/
├── public/
│   └── index.php            # Entry point — routes to Slim or Legacy
├── src/
│   ├── App/
│   │   ├── Controllers/     # Slim HTTP controllers (thin — no DB, no business logic)
│   │   ├── Services/        # Business logic services (injected into controllers)
│   │   │   ├── legacy/      # Reusable legacy PHP code used by services
│   │   │   └── login/       # Action files for LoginService (gradual migration)
│   │   ├── Legacy/          # Legacy PHP scripts (classic REST endpoints)
│   │   │   ├── common/      # Shared utilities (authorize.php, etc.)
│   │   │   ├── login/       # Login-related legacy scripts
│   │   │   ├── device/      # Device-related endpoints
│   │   │   ├── place/       # Place-scoped operations
│   │   │   ├── model/       # Sync and data model scripts
│   │   │   ├── ddbb/        # Database connection wrappers
│   │   │   └── ...
│   │   ├── Middleware/       # Slim middleware (auth, CORS, etc.)
│   │   └── Resources/       # Static resources
│   └── config/
│       └── routes.php       # Slim route definitions
├── composer.json
└── phpunit.xml

Architecture Layers

1. Controllers (Controllers/) — Handle HTTP only. Parse request, call a Service, write the Response. No database access or business logic.
2. Services (Services/) — Business logic. Use injected dependencies (DdbbService, LoggerFactory). May delegate to action files or legacy code.
3. Legacy (Services/legacy/, Legacy/) — Existing PHP scripts kept during migration. Called only through Services, never directly from Controllers.

Database Model

The backend uses two types of databases:

• Central (unpispas): USER, STAFF, PLACE, SESSION, CONNECTED, etc. One per environment.
• Tenant (P + 8-digit place ID): QRCODE, PRODUCT, TICKET, CATEGORY, etc. One database per place.

docker/ — Deployment & Development

docker/
├── docker-compose.yml       # Full stack definition
├── Dockerfile.nxdev         # Development container (Node + PHP)
├── Dockerfile.php81         # PHP-FPM production container
├── public/
│   ├── upp-frontend.conf    # Nginx config for frontend
│   ├── upp-backend.conf     # Nginx config for backend API
│   ├── php-backend.ini      # PHP configuration
│   └── docs/
│       └── nginx.conf       # Nginx config for documentation server
├── letsencrypt/             # TLS certificates (gitignored)
└── logs/                    # Container logs (gitignored)

docs/ — Generated Documentation

docs/
├── codedoc/     # Auto-generated code documentation
├── coverage/    # Test coverage reports (Angular, PHP)
└── swagger/     # API documentation

These are generated artifacts served by the upp-docs container, not manually edited.