Released in 4D v18, project architecture is an important evolution for 4D databases. A project is made of human-readable text-based files, and allows your 4D code to benefit from the power of source control tools. In addition, project architecture natively supports the most modern libraries and interfaces. 

For a comprehensive discussion about projects, please refer to developer.4D.com.

You can convert a 4D binary database (.4db file) into a project, using a simple menu command of your 4D single-user application. Because the export only creates a new version of the existing database, the original files are never touched. Thus, you can convert your database as many times as you need until you are satisfied with the result. Open your .4db database, make some changes, then convert it again and test the results. Each new conversion replaces the previous one. 

Keep in mind that an export is a one-way operation:

• once a 4D database has been exported as a project, both versions become independent of each other. 
• a project cannot be exported to a .4db file
• since projects rely on most modern technologies, they do not support some legacy features. These features are automatically updated if possible or generate conversion errors (see below). 

4D Server: By default, the structure of interpreted projects opened by 4D Server and accessed with 4D in remote mode is read-only (methods, forms, etc. cannot be modified). As explained in this page, multi-user development with projects must rely on standard source control tools. However, if you used to work in team with 4D remote on binary databases, as a first step to a full migration, you might consider using the development mode (see Activate development mode).

When you convert an existing 4D database to a project, the .4db file is left untouched: a folder named "Project" is created next to your .4db file, and will contain all necessary files.

Note: If a folder named "Project" already exists at the same level as your .4db file (for example if a conversion has been done already), it will be replaced by the conversion process. 

To convert a database to a project:

1. Open the database to convert.
2. Select File > Export > Structure to project.  
   

Notes:

• This menu item is only available on 4D single-user.
• This menu item is only available if a binary database is open -- it is disabled in project databases.
• See also the command.

If the conversion is successful and no blocking errors are encountered, the following dialog box is diplayed:

• Reveal log: highlights the conversion log file on your disk. Reading this file is highly recommended since the conversion process could have modified some parts of the application (see Check the conversion section below).
• Open project: restarts the 4D application and loads the converted project. 

The data file is left untouched by the conversion. Only development elements are converted. You can still open the data file with the .4db structure file after a conversion. 

In addition, the Resources, Logs, or Web folders of the .4db are automatically used by the project, with no modification. This makes converting and testing your project easier. 

During the conversion, a new "Project" folder is created at the same level as your .4db structure file. It contains all of your application development as text files: forms, structure, methods, triggers, menus, tips, lists. It also contains a .4DProject file, which is your converted 4D project main file:

When you open the .4DProject file with your 4D application, the project uses the same resources folder and web folder as the existing .4db file, which makes it easier to test your project.

You can still open the .4db database, perform modifications if required (see below), then export it again, and test it. You can repeat this operation until you are satisfied with the conversion.

A log file in JSON format is created by default during the conversion process to reference all issues that required an action from the converter. In this file, messages are classified into three categories ("severity" property), for example:

• info: describes a necessary action executed automatically by the converter that will not have an impact on the application interface or features. For example, if you have images in the pictures library, 4D exports them to the Resources folder of the database (see example above).

• warning: describes a necessary action executed automatically by the converter that could lead to differences in the application's features or interface, but without preventing the database to run. Warnings usually require that you control the impact of the conversion on your code. For example, warnings are returned when unsupported compatibility settings, such as "Unicode mode" or "Radio buttons grouped by name" are automatically switched. 

• error: describes an issue that requires your intervention to be corrected. It can prevent the database from running properly. For example, some legacy form objects are no longer supported, such as highlight buttons. In this case, you must convert the button by yourself to a 3D button in the .4db file before relaunching the conversion operation. 

When edits are required in the .4db database, just modify the code or the form accordingly and export the structure again. Repeat as necessary until you are satisfied with the result. 

During the conversion, some legacy 4D technologies are converted to more modern implementations, and some others are modified or disregarded. In particular:

• The picture library no longer exists in projects. During conversion, 4D exports all of your images to the Resources folder of the database.
• Form objects and form object properties have been updated (they now use the same grammar as Dynamic Forms). Deprecated parts are not supported. 
• Subtables (deprecated since 4D v11, see Subtables) are not supported in projects.
• Nested groups of form objects are not supported in projects (groups are implemented on one level of objects only). During conversion, nested groups are extracted until the lowest level. 
• The Tabable property is not supported in projects because the entry order is managed by the entryOrder collection in Dynamic Forms. During conversion, the collection is automatically filled with respect to the existing entry order configuration (object layering and tabable properties). You may verify in the project database that the form entry order was correctly converted. 
• Database compatibility settings are all reset as for a new database. See the Conversion log file to verify the status of compatibility settings for your database. 
• Form compatibility options (e.g. "Dynamic adjustment","With Constraints") are all reset as for a new form.
• Style sheets are exported as CSS style sheets in JSON files stored in the "/SOURCES" folder named:
• "styleSheets_mac.css" for macOS,
• "styleSheets_windows.css" for Windows.
  
  Applied style sheets are added as "class" attributes to form object JSON descriptions. 
• Form objects automatically expand downwards when the CSS or platform font size is too large. This prevents text from being truncated.
• Output control markers visibility is not preserved when you close and reopen forms in projects. 
• Explorer comments are exported as documentation markdown files (plain text). Refer to developer.4d.com for more information on markdown documentation files. 

The following form objects and properties do not comply with current interface requirements and are now deprecated. They are not supported in Dynamic Forms, and may generate a warning or an error in the project conversion log file (see comments).  

Because of behavior changes in projects, form object rendering can be different when using formatting commands with default or missing parameters.

The following database structure options are deprecated and will be edited or generate errors in the project conversion log file (see comments).  

The following Toolbox editors and features are deprecated and are not supported in projects:

During conversion, existing 4D users and groups are automatically extracted from the .4db file and stored into the directory.json file for the project. 

In projects, since the code is stored in open format text files, the 4D user access management works differently than in binary databases. In particular:

• in single-user mode, the password system is always disabled:
  • the login dialog box is never displayed, 
  • the current user is always the Designer,
  • the settings for SQL server or Web server are ignored (but can be set for client/server deployment).
• there is no difference between users created by the Designer or the Administrator. 
• it is not possible to assign access group or owner group to menus, methods, and forms. Code protection should be handled at the source control tool level.
• user and group IDs (references) are dynamically managed during the session, however they are not stored.

In client-server mode, the user access control works in project databases as in binary databases. However, group assignment to menus, methods, and forms is not supported (see Security Notes).

Consequently, after conversion:

• "Developer" user kind no longer exists, all users (except the Designer and the Administrator) have the "User" kind. 
• Group kind and group owners are removed.
• Static user IDs and group IDs are not kept, except for the Designer (ID=1) and the Administrator (ID=2).
• In the database journal, the "user4D_id" information is replaced by "user4D_alias" which is the 4D user alias (4D user name if no alias was set).

Security Notes: 

• Since project databases do not support group assignment to methods (as well as to menus and forms), they do not allow to control 4DACTION/ urls or 4D Write Pro/4D View Pro formulas through 4D user access. If your database was using this kind of control, you need to use the On Web Connection database method or the “Available through 4D HTML tags and URLS (4DACTION...)” attribute for methods and the for formulas. 

• When you build a client-server project application that controls access through users and groups, make sure to copy the directory.json file in the Settings folder of the data folder so that it is available to the resulting server application. 

Existing custom object libraries (.4il on Windows or .4dlibrary on macOS) must be exported separately if you want to use them in your projects. For more information, please refer to this dedicated blog post.  

4D project deployment strategy is based upon .4dz packed files, where the whole structure is read only. This is the case for merged applications, or compiled components. Consequently, commands that modify the structure will not work and should not be used in deployed applications. If called, they will do nothing, or throw an error, depending on the context. 

Keep in mind that modifying structure files in deployed applications is not recommended for the following reasons:

• it prevents installing merged applications in regular Applications folders, on which users sometimes do not have writing access rights
• it breaks the signature of signed applications, in which case OS can consider they have been infected
• it makes the update of deployed structure versions very complex when local modifications must be saved. 

However, if you absolutely need to avoid the .4dz format and keep your "Project" folder as is, so that you can modify its source files on deployed sites (which is not recommended, as explained above), you may be interested in the PackProject key. 

Here is the list of commands that modify the structure:

When a database is converted to a project, the backup archive counter is reset. It means that the first backup archive file in a converted project will be named  myBase-0001, whatever the sequence number of the last archive file in the binary database.

Actually, the backup archive counter is linked to the database structure file. When you rename or move a .4DB file, and even more so when you convert it to a .4DProject, a new backup counter is started.

Once your are satisfied with your converted database and want to start working on your project, you can clean up your working directory:

1. Remove your .4db and .4dindy files from the application folder (e.g., move them to a backup directory). On macOS, you might need to use the Show package command beforehand, or to remove the .4dbase extension (see below). 
2. On macOS, remove the .4dbase folder extension during the entire development phase. Since you are going to work with text files and put them under a source control tool, you will need to have direct access to them. 

If you want the data file to be open automatically after the project is moved to other machines, you can make it compliant with the project architecture, as described on developer.4d.com:

1. Rename your data file "data.4dd".
2. Create a folder named "Data" and move the data.4dd file within that folder
3. Store the Data folder at the same level as the Project folder.