Handbook Germany: The community to help you get off to a successful start in Germany

Handbook Germany: Together helps new immigrants settle into life in Germany by providing clear, practical information and tips for everyday life. The platform offers guidance in seven key areas of life: work, migration, housing, family, daily life, education, and health. It clearly organizes helpful resources from government agencies, organizations, and associations, making them easily accessible in nine languages.

The platform comes to life through its community forum: After registering, users can ask questions, exchange ideas, and support one another. A team of community managers and experts is actively involved in responding to posts, providing helpful advice, and facilitating dialogue—openly, respectfully, and on an equal footing.

The starting point for the project was to merge the two originally separate systems—a Drupal 7 website and a forum based on OpenSocial—into a unified, scalable, and future-proof headless architecture. 

As a further development, the plan also included setting up an online platform for one-on-one consultations using Symfony. To achieve this, the existing Drupal backend for the website and forum was completely rebuilt, the content was migrated, and the system was connected to a Next.js frontend via a custom-developed API interface. As a result, users experienced a seamless experience across all three systems.

Project Goals and Results

The goal of the Handbook Germany: Together project was to create a central digital platform, unify the systems, and bring them up to the latest technological standards.

Headless System Architecture

From a technical standpoint, the challenge was to merge two existing systems (Drupal 7 for the website and OpenSocial for the forum) into a unified, future-proof platform that is not only easy to maintain editorially but also presents a cohesive look and feel in terms of content, visuals, and functionality. In addition, the platform was to be expanded to include a data-protection-compliant 1:1 online counseling service and a search function for counseling centers (https://handbookgermany.de/de/local-search). All sections had to be designed to be fully translatable into nine languages, implemented in an accessible manner, and seamlessly integrated into the newly developed digital branding. 

To implement the project using a headless system architecture, we utilized the “NextDrupal” Drupal framework developed by the agency Chapter Three, which significantly simplifies communication between a modern, decoupled front end (web app) and the Drupal back end. Technically, it is a Drupal module that is integrated into the existing system, where it provides the necessary interfaces and functional logic.

The framework takes into account the unique features of the Drupal architecture—such as paragraphs, entities, and nodes—along with their specific structures, and provides an optimized abstraction layer. This enables consistent data retrieval and processing. Many functions and conventions are already in place; only a few adjustments are needed to provide or retrieve content via the API.

Using this framework takes the headless concept in Drupal a significant step further: The front end no longer has to conform to the rigid structure of Drupal themes or templates. Instead, it flexibly utilizes the provided APIs, allowing for the integration of modern front-end technology such as Next.js. The clear separation of the back end and front end enhances the maintainability, extensibility, and performance of the overall architecture.

Translation with Lokalise

To translate the content and labels on the pages, we used the “Lokalise” tool, which allows us to import and export translation files containing the corresponding keys along with their translations. This allowed us to ensure that even terms statically embedded in the system—such as those in buttons, forms, etc.—could be translated and easily updated by the Handbook Germany editorial team.

Role Management with Keycloak

In addition to regular users—the largest target group—there are numerous other user groups. A complex permissions and role system assigns different permissions to these groups depending on the platform. For example, the Handbook backend is operated exclusively by the editorial team. The forum is primarily used by three user groups: users, community managers, and consultants. They all require profiles with different features and have different user flows. Online consulting is available only to specific users who have been invited to a consultation by a consultant. 

All of these settings are managed via Keycloak and, depending on the backend system, supplemented with specific additional permissions. Integrating the authentication software with existing and new systems was one of the project’s most significant innovations. Existing user data and roles were migrated, login functionality was implemented in all nine languages—including personalized emails—and sign-in via Facebook and Google was enabled.

Online Counseling with Symfony

Although it was developed in Symfony before the Drupal websites, the online counseling feature marked the completion of the project. The application was to be integrated into the platform as a standalone module while seamlessly blending in with the platform’s look and feel and user experience. Complex processes such as scheduling appointments, filtering by language, region, or counseling topic, the secure exchange of documents, and data protection-compliant communication via Jitsi had to be translated into an intuitive, multilingual user interface—including individual role-based logic for those seeking advice and counselors.

Challenges

One of the biggest challenges of the Handbook Germany: Together project was the technical restructuring of two completely separate systems into a single system architecture featuring a single sign-on system, Lokalise, the online counseling service, and two Drupal backends. This required not only setting up a new technical infrastructure but also ensuring a seamless migration of existing content—particularly forum posts from Open Social, which were migrated along with their respective comments, interactions, and tagged users.

At the same time, full multilingual support in nine languages—including right-to-left languages such as Arabic, Farsi, and Pashto—placed high demands on development and design. All content—from editorial texts to UI elements—had to be maintainable and kept up to date at all times via a central translation system such as Lokalise. Additionally, the design required a flexible layout that functions effectively regardless of the language direction while remaining visually consistent.

To ensure the website’s many features and the high volume of user actions function properly and to minimize the risk associated with deployments, we’ve implemented automated acceptance tests. These tests simulate real-world usage scenarios, such as: A user asks a question, other users receive a notification, and an email is automatically sent. These tests are created once and run automatically with every deployment. This allows us to verify that all key features of the site—especially communication with users—continue to function reliably. These tests enable us to detect and fix errors early on, before they occur in the live environment. 

Conclusion

Handbook Germany: Together is a flagship project showcasing the modern, social, and inclusive use of Drupal within a complex headless architecture. It demonstrates how powerful, flexible, and future-proof open-source technology can be when it is intelligently designed and implemented in a way that adds social value. The project serves as a prime example of how Drupal, as a headless CMS combined with modern frameworks, enables a powerful, multilingual, and socially relevant platform.

For more information, please visit www.sirup.com