Architecture Overview

Syneo/Barcoding is designed as a multi-tier, monorepo-based enterprise system with clear separation of concerns.

System Architecture

┌─────────────────────────────────────────────────────┐
│                    Web Layer                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐        │
│  │ Backend │  │  Front  │  │  Dashboard  │        │
│  │  :4200  │  │  :4201  │  │    :4202    │        │
│  └────┬────┘  └────┬────┘  └──────┬──────┘        │
│       │            │               │                │
│       └────────────┴───────────────┘                │
│                    │                                 │
└────────────────────┼─────────────────────────────────┘
                     │
                     │ HTTP/REST
                     │
┌────────────────────▼─────────────────────────────────┐
│                  API Layer                           │
│            LoopBack 4 REST API                       │
│              :3001/explorer                          │
│                                                      │
│  ┌──────────┐  ┌────────────┐  ┌────────────┐     │
│  │Controllers│  │Repositories│  │  Services  │     │
│  │   606+    │  │    582+    │  │     22     │     │
│  └──────────┘  └────────────┘  └────────────┘     │
└────────────────────┬─────────────────────────────────┘
                     │
                     │ MySQL Connector
                     │
┌────────────────────▼─────────────────────────────────┐
│                Database Layer                        │
│                  MySQL (lb4)                         │
│                                                      │
│  - User data                                         │
│  - Widget configurations                             │
│  - Module data                                       │
│  - Business entities                                 │
└──────────────────────────────────────────────────────┘

Key Architectural Principles

1. Monorepo Structure

All code is maintained in a single repository with multiple projects:

• Simplifies dependency management
• Enables code sharing across projects
• Consistent tooling and configuration
• Atomic commits across multiple projects

2. API-First Design

The LoopBack 4 API serves as the single source of truth:

• All data operations go through the API
• OpenAPI specification auto-generated
• SDK auto-generated from OpenAPI spec
• Consistent interface across all clients

3. Shared Package Strategy

Common functionality is extracted into reusable packages:

• @barcoding/core - Universal utilities
• @barcoding/sdk - API client
• @barcoding/auth-core - Authentication
• @barcoding/gridster-core - Widget system
• App cores - Instance-specific utilities

4. Three-Instance Pattern

Instead of a single monolithic web app, we have three specialized instances:

Backend App (Production Focus)
├── Production analysis
├── Daily operations
└── Manufacturing dashboards

Front App (User Focus)
├── User interactions
├── Job tracking
└── Task management

Dashboard App (External Focus)
├── External views
├── Data visualization
└── Reporting

All three share the same core packages but serve different purposes.

5. Database-Driven Widgets

Widget configurations are stored in the database, not hardcoded:

• Users can add/remove widgets
• Users can resize/reposition widgets
• Per-user customization
• Persistent across sessions

Technology Layers

Presentation Layer (Angular)

Technology: Angular 17.3.12, TypeScript 5.4.5

Responsibilities:

• User interface rendering
• User input handling
• State management (NGXS)
• Routing and navigation
• Widget system

Key Features:

• Three application instances
• 70+ shared packages
• 29 feature modules
• 20 reusable widgets
• Lazy-loaded modules

API Layer (LoopBack 4)

Technology: LoopBack 4, TypeScript 5.2.2, Node.js

Responsibilities:

• Business logic execution
• Data validation
• Authentication/authorization
• Database interaction
• External service integration

Key Features:

• REST API with OpenAPI spec
• JWT authentication
• 606+ controllers
• 582+ repositories
• Dependency injection

Data Layer (MySQL)

Technology: MySQL with LoopBack connector, Knex migrations

Responsibilities:

• Data persistence
• Transaction management
• Data integrity
• Query optimization

Key Features:

• Relational data model
• Migration-based schema management
• Connection pooling
• Multi-statement support

Communication Patterns

Frontend → API

All API calls use the auto-generated SDK:

// Inject SDK service
constructor(private ticketService: TicketControllerService) {}

// Make API call
this.ticketService.ticketControllerFind().subscribe(
  tickets => console.log(tickets),
  error => console.error(error)
);

API → Database

LoopBack repositories handle data access:

// Repository injection
constructor(
  @repository(TicketRepository)
  public ticketRepository: TicketRepository,
) {}

// Database operations
const tickets = await this.ticketRepository.find({
  where: { status: 'open' }
});

State Management

NGXS manages application state:

// Select state
@Select(AuthState.user) user$: Observable<User>;

// Dispatch action
this.store.dispatch(new Login(credentials));

Security Architecture

Authentication

• JWT-based authentication
• Tokens stored in HTTP-only cookies or local storage
• Token refresh mechanism
• Multi-factor authentication support

Authorization

• Role-based access control (RBAC)
• Permission-based guards
• ACL service for fine-grained control
• Route guards protect unauthorized access

API Security

• All endpoints require authentication (except public ones)
• CORS configured for allowed origins
• Request validation and sanitization
• SQL injection prevention via LoopBack ORM

Scalability Considerations

Frontend Scalability

• Lazy-loaded modules reduce initial bundle size
• OnPush change detection for performance
• Virtual scrolling for large lists
• Memoization for expensive calculations

API Scalability

• Stateless API design enables horizontal scaling
• Database connection pooling
• Caching strategies for frequently accessed data
• Async operations for long-running tasks

Database Scalability

• Indexed columns for query performance
• Normalized schema design
• Read replicas for read-heavy operations
• Partitioning strategies for large tables

Next Steps

• Multi-Instance Architecture - Deep dive into the three-instance pattern
• Package Dependencies - Understand package hierarchy
• State Management - Learn NGXS patterns