Skip to main content

Backend Project Structure

This application is built using SOKit, a powerful framework developed by Strategy Object designed to simplify the development of backend systems. It offers built-in support for:

  • document workflows
  • dynamic state transitions
  • declarative security and validation
  • code generation for endpoints

SOKit integrates seamlessly with Keycloak, providing authentication and authorization through role-based access control. In our setup, Keycloak will be used for securing the application, with user roles like COMPANY and OFFICER determining access to specific operations. For containerized environments, we typically run Keycloak using Docker.

For more information about Keycloak and its usage:

If you want to download the already developed backend application click here.

Project Structure Overview​

By exploring the project layout, you’ll notice it is organized into three main modules:

  • data → contains the data layer: entities, embedded objects, and annotations used for persistence and validation.
  • document → defines the document configuration: states, operations, and document metadata.
  • src → represents the business logic: where requests, responses, resolvers, validations, and mappers are implemented.

These three layers will be discussed in detail in the upcoming sections of the guide.

Inside the Business Logic Layer​

Under the src/main/java/com.dev.registration.company, you'll find the core folders that make up the business logic:

  • flow/access → contains access events (role-based authorization checks)
  • flow/events → custom operation or validation events
  • flow/exceptions → exception handling classes used during workflow execution
  • flow/requests and flow/responses → handle request and response event processing
  • flow/search → classes that handle filtering and mapping of search results
  • EventsResolver → central class that links operations to their corresponding events
  • mappers → includes business mappers using MapStruct for clean DTO-to-entity transformations

Don’t worry if this seems like a lot, we’ll build everything step by step in the next chapters.

Technologies in Use​

Moreover, our data layer relies on several tools and frameworks:

  • Hibernate ORM for object-relational mapping and validations
  • Flyway for database migration (though we can disable it in development)
  • Jakarta Persistence API (JPA) for annotations like @Entity, @Embeddable, @Embedded
  • Lombok for boilerplate-free Java classes using annotations like @Getter, @Setter, @NoArgsConstructor
  • Jakarta CDI for dependency injection, with annotations like @ApplicationScoped
  • MapStruct (used later in the mapping layer)

This tutorial will guide you through implementing a company registration system using these tools and SOKit’s document model.
You’ll learn how to define entities, manage document state transitions, secure operations, perform validations, and expose REST endpoints with minimal configuration.