Aam Digital
Enabling social organizations digitally to transform lives.
Aam Digital is an easy-to-use case management software for the social sector that improves the effectiveness and transparency of work with beneficiaries in the field.
For more information about the software and an open demo system visit www.aam-digital.com.
For more information about the code including guides see the separate Developer Documentation
Installation, Use & Deployment
You can directly run the system using Docker. More information in our Aam-Digital/ndb-setup repository. In that case you do not have to clone this repository and install all the dependencies as everything is packaged into the docker image already.
The Aam Digital platform can be customized for different use cases through a flexible configuration file. This doesn't require changes to the generic platform code base in this repository:
The overall architecture and tech stack including backend services looks like this:
Development
Setup
- This project depends on npm (NodeJS) to setup its dependencies. Please make sure you have npm installed. The Node.js version used in CI is in
.nvmrc(with nvm:nvm use); CI uses the npm that comes with it. git clonethis repository to get all the code with its configuration and requirements.npm installthe dependencies (external libraries and packages)npm run startto run your local dev server and get started.
By default, the app is started with a "mock" session, generating demo data into an in-memory database. You can change this mode by editing the environment.ts (or create a file assets/config.json to overwrite settings; that file is on the .gitignore list).
If you need to develop in an advanced environment including local backend services, please refer to the instructions at Aam-Digital/aam-services/docs/developer.
Documentation
Our detailed Developer Documentation provides tutorials, guides, concepts and an API reference.
Module-level documentation
Core modules have technical README.md files in their directories
for developers and agents to avoid expensive code exploration.
These provide architecture overviews, file organization, key concepts, and patterns specific to that module.
For example:
- Entity system — entity base class, schema, load/save, lifecycle actions
- Configuration system — how the JSON config drives views, menus and entities
- Permissions module — CASL-based role/permission enforcement
Translations (internationalization; i18n)
Aam Digital is available in multiple languages. We translate the terms using POEditor: Join the translation team
To commit latest translations to the codebase, trigger the manual GitHub Action in the repository.
Code Style
We use prettier to enforce a consistent formatting of code to make the project easier to read. The project is set up with a git pre-commit hook to automatically format your commits according to these rules.
Using Angular CLI
This project is built upon Angular.
If you are unfamiliar with the framework and Angular CLI go check out the Angular CLI README or use ng help.
Design & UX
We have a Design System built in Figma with various building blocks for quick mockups:
Figma: Aam Digital - Design System
Build a docker image locally
Deployment on a server can be done through a docker image, our ndb-setup project provides tools and a starting point to run the system using docker. For more information about Docker, please refer to their official documentation.
To learn more about the build process, see /build.
AI-Assisted Development
This project supports AI-assisted development through GitHub Copilot, Claude Code, and CodeRabbit.
| Tool | Usage |
|---|---|
| GitHub Copilot (VS Code) | Code generation, chat, agent mode — reads AGENTS.md. Use Plan mode for architecture planning before implementation. |
| Claude Code (CLI) | Interactive coding assistant — reads AGENTS.md (do not add a CLAUDE.md, it would replace AGENTS.md) |
| CodeRabbit (GitHub) | On-demand PR reviews — configured via .coderabbit.yaml. Comment "@coderabbitai review" on a PR to trigger a review (auto-review is disabled). |
Skills
Shared skills are defined in .claude/skills/. Claude Code picks the matching one from what you ask
(e.g. "can you do a code review of PR 4526"), or you call it by name (e.g. /review-pull-request 4526).
A feature usually goes through them in this order: use cases, prototype, plan, then the code, then the review.
| Skill | Purpose |
|---|---|
feature-use-cases | Write the use cases for a new feature |
design-prototype | Build a clickable prototype with the Aam Digital design system |
figma-mockups | Design screens in the Aam Digital Figma design system file |
plan-implementation | Write the implementation plan for an issue |
review-pull-request | Review a pull request |
translate-base-configs | Translate the base configs of a use case into another language |
Set up once: open Claude Code in this repository and trust the folder, and log in to the GitHub CLI
(gh auth login). design-prototype needs the Artifact tool (log in with your Claude account) and view access
to the Aam Digital design system, figma-mockups the Figma connector. The skills write drafts and never
post to GitHub, you paste the result yourself.
MCP Servers
MCP servers are configured in .vscode/mcp.json:
- angular-cli — Angular CLI operations, schematics, component generation
- chrome-devtools — Runtime debugging, DOM inspection, console access
- sentry — Production error data, issue investigation (requires
SENTRY_AUTH_TOKENenv var) - github — Issues, PRs, diffs, repository context (requires
GITHUB_PERSONAL_ACCESS_TOKENenv var)
Tips for Effective Prompting
- Be specific about the entity/component you're working with
- Reference existing patterns and similar implementations
- Let agents read relevant files first before making changes
- Use the agent files as starting points for common workflows
Contribute
Our project is completely run by volunteers. Contributions welcome!
We are trying hard to make it easy for you to join in. As a starting point, please refer to our CONTRIBUTING page.