# Project pack: Tududi @ fd80157

Facts about **Tududi** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Tududi is a self-hosted task manager for one person or a small household. You sort life into areas, projects and tasks, keep notes alongside them, and get a daily view of what matters. It works with recurring tasks and Telegram and runs as a small Docker container.

## Version and source
- Repository: https://github.com/chrisvel/tududi
- Pinned commit: `fd80157b851f7b046cf0b0f9f56be627f97b04b5`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/chrisvel/tududi/archive/fd80157b851f7b046cf0b0f9f56be627f97b04b5.zip
- Official docs: https://docs.tududi.com
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/chrisvel/tududi bespoke-tududi
  cd bespoke-tududi
  git checkout --detach fd80157b851f7b046cf0b0f9f56be627f97b04b5
  # Prepare development requirements and local configuration first.
  npm install
  npm run backend:dev
  npm run frontend:dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name tududi -p 3002:3002 -e TUDUDI_USER_EMAIL=you@example.com -e TUDUDI_USER_PASSWORD=choose-a-strong-password -e TUDUDI_SESSION_SECRET=replace-with-a-long-random-string -v tududi_db:/app/db -v tududi_uploads:/app/uploads chrisvel/tududi:latest
  # then open http://localhost:3002
  ```

- Needs: Docker for a trial, Node 22 for development
- Develop: `npm run backend:dev  # and, in another terminal: npm run frontend:dev`
- Test: `npm test`
- Check/lint: `npm run lint`
- Stack: typescript, javascript (React, Express, Sequelize, Webpack). Difficulty for a non-developer with an AI: **easy**. A compact Node and React app with SQLite and no external services. Most changes are a component, a route and a migration.

## The project's own AI instructions
Read these in the repository before changing code: `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **areas-projects** [settings]: Organise tasks around life areas such as Home, Health and Work. → `Sidebar → Areas and Projects`
- **recurring-and-reminders** [settings]: Repeating tasks and nudges in Telegram. → `Task editor → Recurrence, Telegram settings`
- **theme-and-language** [settings]: Dark mode and translations. → `Settings → Appearance, Language`
- **api** [extend]: Add tasks from scripts, shortcuts or other apps. → `/api routes in backend/ (API key in Settings)`
- **frontend** [code]: New screens, fields and views. → `frontend/components and frontend/entities`
- **backend** [code]: New task fields and rules. → `backend/modules, backend/models, backend/migrations`

## Must keep working
- Sequelize migrations in backend/migrations. Add new ones; never edit old ones.
- Login, session secret handling and the API key checks.
- Recurring task generation.

## Staying updatable
Keep changes small and in new files. Add a component, a route and a migration rather than rewriting existing screens.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite database and uploads in /app/db and /app/uploads (Docker volumes). Back up the db and uploads folders.
- Service: Telegram bot (BotFather) (optional, free): Add tasks and get reminders from chat.
- Setting `TUDUDI_USER_EMAIL`: The first user's login email.
- Setting `TUDUDI_USER_PASSWORD` (**secret**: the person enters it themselves, never in chat): The first user's password. Never paste it into an AI chat.
- Setting `TUDUDI_SESSION_SECRET` (**secret**: the person enters it themselves, never in chat): Long random string used to sign logins. Never paste it into an AI chat.
- Use a strong password and a long random session secret, and keep both out of Git.
- Put it behind HTTPS if you open it to the internet.

---

# Customising Tududi

Tududi is small enough to understand in an afternoon: a React front end, an Express back end and a SQLite database.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and components | frontend/components/ |
| Data shapes used by the screens | frontend/entities/ |
| API routes and business logic | backend/modules/ and backend/routes/ |
| Database models | backend/models/ |
| Database migrations | backend/migrations/ |
| Translations | frontend/ locale files and the linguaisync config |
| Tests | backend/tests/, frontend/__tests__/, e2e/ |

## Use the gentlest change first

1. **Settings (no code):** areas, projects, recurrence, reminders, theme and language.
2. **Extend:** the API for scripts and shortcuts.
3. **Code:** new fields, views and rules.

## Recipes

- **New field on a task:** add a Sequelize migration, add it to the model, accept it in the module's route, then add it to the task form.
- **New view:** copy an existing page component, add a route and a sidebar link.

## Running and checking your changes

- Run backend and frontend dev servers, add a task, complete it and delete it.
- `npm test` for backend tests and `npm run frontend:test` for the UI tests.
- Run `npm run lint` before you finish.

## Pitfalls

- Never commit the `db/` folder, it holds personal data.
- Add translation keys for new text.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/tududi/fd80157/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/tududi/fd80157/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/tududi/fd80157/r2/SKILL.md)