Ever struggled to find who works on what team, who to contact for a project, or how your organization is structured?

Directory Navigator is a web-based directory that helps organisations keep track of people and teams in one searchable, visual place. Features include:

• People and team profiles - Photos, contact details, bios, job titles, team memberships, team goals and more.
• Flexible team management - Track official hierarchies, working groups, interest groups, social clubs, or any other grouping that matters to your org. People can have different roles across multiple teams.
• Rapid search - Quick Cmd+K search across people and teams.
• Visual org charts - Autogenerated organograms from your team structures make organizational structure clear at a glance.
• Wiki-like editing - Users can keep profiles, teams and relationships up to date. Audit logs ensure admins can view who edited what, when, and why.
• API access - Import, export, sync or search your data via the API - to work great with your existing systems.
• SSO integration - Sign-in with Google, Microsoft, GOV.UK Internal Access, OIDC, or email. Admins control who can log in, and their group-based permissions.

You only need to do this once.

1. Install Node (choose the LTS version) and VS Code
2. Install Java (choose the latest LTS version)
3. Clone the repository (more info)
4. Open the folder with VS Code
5. Run npm install in the root

Summary: start everything with npm start, then visit localhost:8000

All commands are run from the root of the repository. Any of the turbo commands can be filtered with -- --filter @odir/<app>, for example to start just web run npm start -- --filter @odir/web

These scripts are defined in the relevant package.json files. We keep these scripts as simple to use as possible, so developers need to run very few commands. We also keep these scripts consistent so that they behave as expected across the repo, and we need less config overrides.

All packages should have their main content in a src folder, and output built files to dist.

To install external packages (choosing the appropriate workspace, and with the argument --save-dev for dev dependencies):

npm install some-package-name --workspace @odir/server

And to uninstall:

npm uninstall some-package-name --workspace @odir/server

web:

• 8000: the website

server:

• 8001: the API
• 8002: serverless-offline websockets
• 8003: serverless-offline AWS Lambda API
• 8004: serverless-dynamodb instance of DynamoDB for serverless-offline
• 8005: serverless-dynamodb instance of DynamoDB for tests
• 8006: serverless-offline-ses-v2 instance of ses
• 8007: serverless-s3-local instance of S3

We follow the GitHub flow model (aka: feature branches and pull/merge requests).

Try to make small, independent changes to make reviewing easy and minimize merge conflicts. Follow existing conventions and leave comments explaining why the code you've written exists/exists in the way it does.

To learn more about using Git, see the VS Code source control documentation or read the free Git book.

1. Check you're up to date with the latest changes in the repository, using VS code (select master branch, then 'Synchronize Changes' button) or git commands (git checkout master && git pull). Make sure you've also updated dependencies by running npm install.
2. Create a feature branch for your work, using VS code (select branch > 'Create new branch') or git commands (git checkout -b my-new-feature)
3. Make your changes.
4. Check your changes work as expected, and ideally write some unit tests for them. Run npm test to run them.
5. Commit your changes, and push the branch. Raise a pull request and get someone to review it. If you've paired on a piece of work, still review the changes you've made but you can merge if you are both happy.
6. Merge once you and your reviewer are happy, and the CI pipeline passes.

• user: Any human person that can login to the directory.
• group: A collection of zero or more users, to control permissions to viewing details of certain persons or teams. This includes a special 'admin' group which can manage all groups.
• person: A person in the directory. The plural we use is 'persons'. Usually corresponds to exactly one user. May be part of zero to many teams, but most often will be just on one team.
• team: A team in the directory. May have relations between it and many other teams/persons.
• relation: A relationship between persons and/or teams. Used for example to record team membership (person -> team), team nesting (team -> team), line managers (person -> person).

Think any documentation is out of date, incomplete, misleading or otherwise could be improved? Open a pull request or raise an issue.

• 🌐 Website
• 🔃 Server
• 📦 Shared