# Teepy × Theopy — my contribution (sanitized extract)

This repository is a **sanitized extract** of [Teepy](https://github.com/Kozea/teepy),
Kozea's proprietary pharmacy-management ERP (private repository, years of
work by a full team, confidential to Kozea and its clients).

It exists to show, publicly and without breaching confidentiality, the code I
personally wrote to connect Teepy to **[Theopy](https://github.com/SajedehAdelia/Theopy)**,
an AI assistant I built as part of my RNCP39583 "Experte en Développement
Logiciel" certification.

**Every file and folder from the real Teepy repository is present here, at
its real path, so the overall structure of the application is visible — but
only the files I personally authored keep their real content. Everything
else has been emptied (zero bytes) on purpose.** This repo carries no git
history from the original: only Teepy's own private repository has that.

## Where my contribution sits in the architecture

```
 ┌─────────────────────────────────────────────────────-─────────────────┐
 │  THEOPY  (public, separate repo)                                      │
 │  AI assistant — Gemini / Ollama brain, chat UI, login                 │
 └────────────────────────────────┬──────────────────────────────────────┘
                                  │  MCP protocol over SSE
                                  │  initialize → tools/list → tools/call
                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  TEEPY  (this repo — sanitized)                                      │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │ mcp_server.py                                        ★ MINE  │    │
│  │ FastMCP entrypoint - boots the MCP server on :5001           │    │
│  └────────────────────────────┬─────────────────────────────────┘    │
│                               │                                      │
│  ┌────────────────────────────▼───────────────────────────────--─┐   │
│  │ mcp_tools/                                           ★ MINE   │   │
│  │  core.py       - identity resolution via MCP `meta`,          │   │
│  │                  requires_role() access control               │   │
│  │  invoices.py   - factures  (administrator/manager/commercial) │   │
│  │  customers.py  - clients   (administrator/manager/commercial) │   │
│  │  plannings.py  - plannings (administrator/manager/operator)   │   │
│  │  sessions.py   - sessions  (+ contractor)                     │   │
│  │  reminders.py  - relances  (administrator/manager/commercial) │   │
│  └────────────────────────────┬───────────────────────────────-──┘   │
│                               │  calls agent_* functions             │
│  ┌────────────────────────────▼──────────────────────────────-───┐   │
│  │ teepy/routes/theopy/                                 ★ MINE   │   │
│  │  base.py, customer.py, invoice.py, planning.py,               │   │
│  │  reminder.py, session.py                                      │   │
│  │  → agent-facing business logic, wrapping Teepy's existing     │   │
│  │    repositories/models                                        │   │
│  └────────────────────────────┬─────────────────────────────-────┘   │
│                               │                                      │
│  ┌────────────────────────────▼─────────────────────────-────────┐   │
│  │ teepy/routes/theopy_auth.py                          ★ MINE   │   │
│  │  POST /api/theopy/authenticate                                │   │
│  └────────────────────────────┬───────────────────────────────-──┘   │
│                               │  queries through                     │
│  ┌────────────────────────────▼─────────────────────────────-────┐   │
│  │ teepy/models/, teepy/repositories/, teepy/services/,          │   │
│  │ teepy/routes/ (rest), teepy/templates/, teepy/static/, ...    │   │
│  │                                        ○ PRE-EXISTING TEEPY   │   │
│  │        proprietary ERP - content redacted in this repo        │   │
│  └────────────────────────────┬───────────────────────────────-──┘   │
│                               │                                      │
│  ┌────────────────────────────▼────────────────────────────-─────┐   │
│  │ PostgreSQL (Teepy production database)                        │   │
│  └────────────────────────────────────────────────────────────--─┘   │
└────────────────────────────────────────────────────────────────--────┘
```

`★ MINE` = full, real content, kept as-is.
`○ PRE-EXISTING TEEPY` = real file/folder structure preserved, content emptied.

## What's mine, in full

| Path | What it is |
|---|---|
| `mcp_server.py` | FastMCP entrypoint for the MCP server |
| `mcp_tools/` (6 files) | Role-based access control layer over every MCP tool |
| `teepy/routes/theopy/` (6 files) | Agent-facing business logic (customers, invoices, plannings, reminders, sessions) |
| `teepy/routes/theopy_auth.py` | `POST /api/theopy/authenticate` - the endpoint Theopy's login calls |
| `test/theopy/` (7 files) | Tests for the MCP tools and agent-facing functions, run against real business logic and a real database |
| `test/test_theopy_auth.py` | Tests for the authentication endpoint |
| `Makefile` | Includes commands I added: `theopy-serve`, `mcp-inspect`, `install-db-test` |
| `docker-compose.yml` | MCP server port (`5001`) and networking added for Theopy to reach Teepy |
| `sql/dev_data.sql` | Additional seed rows I added (synthetic dev data only, not real customer data) for realistic testing |
| `requirements/`, `uv.lock` | Dependency additions for the MCP integration |

`teepy/__init__.py` is intentionally emptied too, even though I added 2 lines
to it (registering the `theopy_auth` blueprint) - the file is overwhelmingly
pre-existing Teepy bootstrap code, not mine, so it follows the same rule as
everything else outside the list above.

## Links

- **Theopy** (the AI assistant, fully public): https://github.com/SajedehAdelia/Theopy
- **Teepy** (the real repository, private - access on request): https://github.com/Kozea/teepy