docs/DeveloperDocs/Directory-Structure.md
The sections below walk through the directories in detail. This table is the whole tree at a glance, because the detail is easy to get lost in - and because for years this page described four directories out of twenty and did not say so.
| Directory | What is in it |
|---|---|
| client/ | everything the browser runs: Blaze components, their styles, the client-side libraries |
| server/ | everything only the server runs: startup, publications, methods, the REST routes, lib/ |
| models/ | the collections, their schemas, helpers and mutations - shared by both, so a model must never import from server/ |
| imports/ | shared code that is neither a model nor a component: i18n, the reactive cache, the shared SimpleSchema, startup |
| packages/ | the Meteor packages WeKan maintains itself - the accounts integrations (CAS, LDAP, OIDC, Sandstorm), the lockout, markdown |
| config/ | the router and the accounts configuration |
| migrations/ | one file per database migration, run in order at startup |
| public/ | files served as-is: icons, fonts, the web app manifest |
| private/ | files the SERVER can read and the client cannot |
| tests/ | the suites - *.test.cjs run by tests/run-node-suites.cjs, plus the Playwright and e2e directories |
| docs/ | this documentation |
| releases/ | how a release is built and published - the bundle steps, the translations tooling, the CHANGELOG tooling |
| snap/, snap-src/, snap-base-debian/ | the snap package |
| sandstorm-src/ | the Sandstorm package |
| openapi/ | the REST API description, generated from the routes |
| meta/ | signatures, icons, screenshots, project description |
| old-CHANGELOG/ | the CHANGELOG's history, by year and by month (CHANGELOG.md holds the current month) |
.tools/ | NOT part of this repository: the companion repos and toolchains a build needs, ignored by git and by Meteor |
node_modules/, .meteor/, .build/ | generated; never edited, never committed |
Two rules that the layout only implies:
models/ is shared code. It is loaded on the client too, so a model that
imports from server/ breaks the client build. Server-only logic that a model
needs lives behind Meteor.isServer or in server/lib/..jade file is not picked up by being on disk. Every template is
imported by name from client/features/*.js, and a component .js that other
components import must import its own .jade - see
tests/clientBundleImports.test.cjs and tests/templateRegistration.test.cjs.We're using FlowRouter client side router inside config/router.js. For accounts there is AccountsTemplates configured in config/accounts.js.
Files in this directory are served by meteor as-is to the client. It hosts some (fav)icons and fonts.
svg-etc/manifest.json: goes into link rel="manifest" in the header of the generated page and is a Web App Manifest.
activities template for the list of activities placed inside a sidebar-content; uses boardActivities or cardActivities depending on mode; <span style="color:red">XXX: does this mean that sidebar should be visible in board list mode? when does the board activity gets shown?</span>commentForm template used in card-details-canvas for adding comments;archivedBoards template for the modal dialog showing the list of archived boards that might be restored;board and, based on screen size and current state, it uses either cardDetails or boardBody templates; boardBody is the one including the sidebar, each list, cardDetails for larger screens when a card is selected and the addListForm for adding a new list (also defined in this file);boardHeaderBar, boardMenuPopup, boardVisibilityList, boardChangeVisibilityPopup, boardChangeWatchPopup, boardChangeColorPopup, createBoard, chooseBoardSource, boardChangeTitlePopup, archiveBoardPopup, outgoingWebhooksPopup;boardList and boardListHeaderBar for the list of boards in the initial screen;cardAttachmentsPopup, previewClipboardImagePopup, previewAttachedImagePopup, attachmentDeletePopup, attachmentsGalery;editCardDate and dateBadge templates;boardsAndLists is the usual layout for a board display with boardLists being used in sandstorm where each board is independent;cardDetails, editCardTitleForm, cardDetailsActionsPopup, moveCardPopup, copyCardPopup,cardMembersPopup,cardMorePopup, cardDeletePopup;editCardSpentTime and timeBadge templates;checklists, checklistDetail, checklistDeleteDialog, addChecklistItemForm, editChecklistItemForm, checklistItems, itemDetail;formLabel, createLabelPopup, editLabelPopup, deleteLabelPopup, cardLabelsPopup;minicard templateinlinedForm template;importHeaderBar, import, importTextarea, importMapMembers, importMapMembersAddPopup are all templates used for importing Trello (via trelloMembersMapper.js) and Wekan (via wekanMembersMapper.js) boards;list is the simple, main template for lists;listBody, addCardForm, autocompleteLabelLine templates;listHeader, editListTitleForm, listActionPopup, boardLists, listMorePopup, listDeletePopup, setWipLimitPopup, wipLimitErrorPopup templates;editor and viewer templates;header and offlineWarning templates; if the user is connected we display a small "quick-access" top bar that list all starred boards with a link to go there (this is inspired by the Reddit "subreddit" bar); the first link goes to the boards page;shortcutsHeaderBar, shortcutsModalTitle, keyboardShortcuts - all for the shortcuts that are presented when you press ?re implemented inhere;userFormsLayout, defaultLayout, notFound, message;popup in this case);statistics template — the Version pane of Admin Panel / Settings, five tables (Platform, OS, Meteor, Database, Node). There is no information template any more: it is a pane rendered by settingBody.jade, not a page;invitationCode template;people, peopleGeneral, peopleRow, editUserPopup;setting, general, email, accountSettings, announcementSettingssettingHeaderBar template;sidebar, homeSidebar, membersWidget, labelsWidget, memberPopup, removeMemberPopup, leaveBoardPopup, addMemberPopup, changePermissionsPopuparchivesSidebarfilterSidebar, multiselectionSidebar, disambiguateMultiLabelPopup, disambiguateMultiMemberPopup, moveSelectionPopup;userAvatar, userAvatarInitials, userPopup, memberName, changeAvatarPopup, cardMemberPopupheaderUserBar, memberMenuPopup, editProfilePopup, editNotificationPopup, changePasswordPopup, changeLanguagePopup, changeSettingsPopup;client/features is the list of what the client
LOADS. One file per area - boards.js, cards.js, settings.js, main.js and
so on - each importing that area's .jade, then its .js, then its .css, and
client/imports.js imports them all. A component that is not named here is not
in the bundle, however finished it is: tests/templateRegistration.test.cjs
fails when a template is included by name and never imported.
currentBoard(), currentCard(), getUser() and concat();watch and unwatch from Firefox prior to version 58;CSSEventsobject has methods that select the name of the event based on the specific transitions and animations;Show on Card or Show on Minicard;Hide minicard label text setting (the user's profile, or this browser when nobody is logged in), used by the minicard and by Minicard menu / Show on Minicard;Activities;?re implemented inhere;Popup class for things likes electing a date; <span style="color:red">XXX: not a Blaze helper?</span>Filter Blaze helper to support filtering cards by labels and by members;Modal Blaze helper to support showing modal windows like the one for archived boards;Modal Blaze helper to support multiple selection mode;getUnsavedValue and hasUnsavedValue Blaze helpers to preserve content entered in fields but not saved;.js files in this directory are not available to the client.
The four directories that hold most of it:
server/lib - the server-only libraries the rest of it calls. The security log and the event-log fold that Admin Panel / Problems is built on, the login throttle and timing defence, the database problem classifier, the API usage counter, the recovery and migration helpers.
server/methods - Meteor methods that are not part of a model: the backups, the repairs, the reports the Admin Panel calls.
server/publications - what the client may subscribe to, and with which fields.
server/routes - the HTTP routes that are not the
REST API: the avatar server, the attachment routes, the custom head assets.
The REST API itself is registered by the models, in front of
server/apiMiddleware.js - body parsing,
the WITH_API gate, bearer-token authentication, and the usage counting
behind Admin Panel / Problems / API.
server/startup and the 00*.js files at the top -
what runs before anything else, in name order: the startup checks, waiting for
the database, the retry-on-busy wrapper, the error handlers.
statistics.js implements a Meteor server-only method for general-purpose information such as OS, memory, CPUs, PID of the process and so on.
migrations.js is where code that update sold databases to new schema is located. Anytime the schema of one of the collection changes in a non-backward compatible way a migration needs to be written in this file.
authentication.js add the Authenticationobject to Meteor that provides methods for checking access rights.
lib/utils.js defines some checks used by checklists.js** model. <span style="color:red">XXX: these methods are defined in server-only code by are used in models, which are visible by the client (in Checklists.allow)?</span>
Notifications object that supports Activities and holds a list of functions to call when its notify() method is called along with convenience methods to subscribe, unsubscribe and a way to filter recipients according to user settings for notification;
watch() Meteor server-only method that may watch boards, lists or cards using models/watchable.js;outgoingWebhooks() Meteor server-only method that can call external API <span style="color:red">XXX: I guess</span>publications defines sets of records that are published by the server and how clients can subscribe to those:
The files in models directory mainly define collections; most of them have aldeed SimpleSchema for automatic validation of insert and update of collections. This is also where helpers, mutations, methods, hooks and bootstrap code is to be found. Server side code also implements json REST API.
models/lib is the other half of this directory, and by
file count the larger one: the PURE modules a model, the server and the client
all share - the event-log summary shape, the address classifier, the admin URLs
and menus, the shared table page, the lockout state, the map links. They are
plain CommonJS with no Meteor in them, which is what lets
tests/*.test.cjs run them under bare node and test a decision as arithmetic
rather than through a server.
Collections (mostly Mongo.Collection except as noted) are defined in:
Meteor.users collection.Other files:
Boards, Lists and Cards.importBoard() method so that Trello (in trelloCreator.js) and Wekan (in wekanCreator.js) boards can be imported. <span style="color:red">XXX: Solid candidates for a directory of their own.</span>meteor build).# Upcoming section; takes no version number.CHANGELOG.md into old-CHANGELOG/.*.test.cjs suites run by
run-node-suites.cjs (all of them, with
every failure listed at the end), plus the Playwright browser tests and the
e2e/import suites. Many of them READ THE SOURCE and pin a behaviour, which is
what makes "and this mistake is nowhere else in the tree" checkable.release-all.yml is the
release: the bundles for every platform, the Docker images, the snaps, and the
GitHub Release they attach to.This page was contributed by TNick and
xet7 when WeKan was at commit
e2f768c,
and it described the tree as it was then for a long time afterwards: fourteen of
its links pointed at files that had moved or been deleted, and two thirds of the
repository - imports/, packages/, releases/, tests/, docs/,
migrations/, server/lib, server/methods, server/routes, models/lib,
client/features - was not mentioned at all.
Please add new files, fixes and updates directly to this page.
tests/docsLinksResolve.test.cjs fails when a link here points at something that
is not in the tree, which is what let the fourteen rot unnoticed: a
https://github.com/wekan/wekan/tree/main/... link looks fine in an editor and
404s only for the reader.