# AGENTS.md

Entry point for any AI agent working on this repository. Read this first,
then follow the pointers below for detail.

## Project

Normogen — open-source health data platform. Monorepo:

- `backend/` — Rust (Axum + MongoDB)
- `web/normogen-web/` — React + TypeScript (Material-UI, Zustand)
- `docs/` — architecture, product status, testing scripts
- `shared/` — types/contracts shared across packages

Stack detail, architecture, and code patterns: see
[docs/AI_AGENT_GUIDE.md](docs/AI_AGENT_GUIDE.md) and
[docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).

## Working directory

Absolute paths are preferred. Project root: `/home/asoliver/desarrollo/normogen`.

## Issue-driven workflow (source of truth for tasks)

Bugs and features are tracked in **Forgejo** at
`https://gitea.soliverez.com.ar/alvaro/normogen`. This is the canonical
backlog — do not invent tasks independently; pick up work from open issues or
discuss before creating new ones.

- Report → triage → implement → close, in chunks tied to one issue each.
- Reference the issue number in branch names (`fix/123-…`, `feat/456-…`) and
  commit messages (`fix(medication): … (#123)`).
- The Forgejo API token lives in `.forgejo-token` (gitignored). Read it with
  `cat .forgejo-token`; pass it as `Authorization: token $(cat .forgejo-token)`.
  **Never** echo the token value, commit it, or paste it into issue/commit text.
- Full lifecycle and API call patterns are documented in the
  "Issue-Driven Workflow" section of [`.gooserules`](.gooserules).

## Before making changes

1. Read [docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).
2. Check [docs/product/STATUS.md](docs/product/STATUS.md) for current progress.
3. Check open Forgejo issues for the task at hand and its prior discussion.
4. Review existing code patterns before introducing new ones.
5. Plan the approach and confirm before implementing non-trivial changes.

## Essential commands

```bash
# Backend
cd backend && cargo build
cd backend && cargo test
cd backend && cargo clippy
cd backend && docker compose up -d

# Frontend
cd web/normogen-web && npm install
cd web/normogen-web && npm start
cd web/normogen-web && npm test

# Integration tests
./docs/testing/quick-test.sh
./docs/testing/test-api-endpoints.sh
```

## Commit guidelines

Conventional Commits: `feat(scope): …`, `fix(scope): …`, `docs: …`, etc.
Reference the issue number when the commit closes or advances one:
`fix(medication): resolve adherence bug (#123)`.

## Where things live

| Concern | Location |
|---|---|
| Backend handlers | `backend/src/handlers/` |
| Backend models | `backend/src/models/` |
| Routes | `backend/src/main.rs` |
| Frontend pages | `web/normogen-web/src/pages/` |
| Frontend API services | `web/normogen-web/src/services/` |
| Shared types | `shared/`, `web/normogen-web/src/types/api.ts` |