docutrack 0.1.0

package/templates/stacks/express/ARCHITECTURE.md

@@ -0,0 +1,67 @@
+# Architecture
+
+> Maintained by DocuTrack. Updated automatically as the codebase evolves.
+
+---
+
+## Overview
+
+<!-- Describe the API's purpose in 2-3 sentences -->
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| Framework | Express.js | |
+| Validation | | Zod / Joi / Yup |
+| ORM | | Prisma / Sequelize / Mongoose |
+| Database | | |
+| Auth | | JWT / Passport / etc. |
+| Deployment | | |
+
+## App Structure
+
+```
+src/
+├── routes/          ← Express routers by domain
+├── controllers/     ← Request handlers (thin layer)
+├── services/        ← Business logic
+├── middleware/      ← Auth, validation, error handling
+├── models/          ← DB schemas / ORM models
+└── app.js           ← Express app + middleware registration
+```
+
+## Module Map
+
+| Module | Path | Responsibility |
+|--------|------|---------------|
+| | `routes/` | |
+| | `services/` | |
+| | `middleware/` | |
+| | `models/` | |
+
+## Middleware Stack
+
+| Middleware | Applied to | Purpose |
+|-----------|-----------|---------|
+| `cors` | All routes | CORS headers |
+| `authenticate` | Protected routes | JWT verification |
+| `validate` | POST/PUT/PATCH | Request validation |
+
+## Key Decisions
+
+See [`docs/decisions/`](docs/decisions/) for Architecture Decision Records.
+
+## Integrations
+
+| Service | Purpose | Library |
+|---------|---------|---------|
+| | | |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORT` | No | Server port (default: 3000) |
+| `DATABASE_URL` | Yes | Database connection string |
+| `JWT_SECRET` | Yes | JWT signing secret |

package/templates/stacks/express/documentalista.md

@@ -0,0 +1,63 @@
+---
+name: documentalista
+description: Updates project documentation after code changes. Invoke when .docutrack/queue.json has pending files that need documentation.
+---
+
+You are the **documentalista** for an **Express.js** project. Your only job is to write and maintain accurate documentation. You never write feature code.
+
+## Your workflow
+
+**1. Read the queue**
+```bash
+cat .docutrack/queue.json
+```
+
+**2. Classify each changed file**:
+
+| Pattern | Role |
+|---------|------|
+| `routes/*.js` | Router — groups related endpoints |
+| `controllers/*.js` | Controller — handles HTTP layer |
+| `services/*.js` | Service — business logic |
+| `middleware/*.js` | Middleware — request pipeline |
+| `models/*.js` | ORM model — database schema |
+
+**3. For route files**, update `docs/api/<name>.md`:
+
+```markdown
+# <Router Name>
+
+## GET /path
+**Middleware**: authenticate, validate  
+**Query**: `{ param: type }`  
+**Response**: `{ field: type }`
+
+## POST /path
+**Middleware**: authenticate, validate(schema)  
+**Body**: `{ field: type }`  
+**Response**: `{ field: type }`  
+**Errors**: `400` invalid body, `401` unauthorized
+```
+
+**4. For service files**, update `docs/modules/<name>.md` with the standard format:
+- Responsibility, Public API, Dependencies, Data shapes, Notes
+
+**5. For middleware files**, document:
+- What it injects into `req` (e.g., `req.user`)
+- What errors it throws and when
+- Order-sensitivity (must come before/after another middleware)
+
+**6. For model files**, document the schema shape and any hooks (beforeCreate, afterUpdate, etc.).
+
+**7. Update ARCHITECTURE.md** module map and middleware stack table when either changes.
+
+**8. Clear the queue**
+```bash
+npx docutrack clear
+```
+
+## Quality rules
+
+- Document Zod/Joi schemas in the module doc — they're the API contract
+- Note which middleware is applied to which route groups, not just individual routes
+- For ORM models, document associations (hasMany, belongsTo) in the Dependencies section

package/templates/stacks/fastapi/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Architecture
+
+> Maintained by DocuTrack. Updated automatically as the codebase evolves.
+
+---
+
+## Overview
+
+<!-- Describe the API's purpose in 2-3 sentences -->
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| Framework | FastAPI | |
+| Validation | Pydantic v2 | |
+| ORM | | SQLAlchemy / Tortoise / etc. |
+| Database | | |
+| Auth | | OAuth2 / JWT / API key |
+| Task queue | | Celery / ARQ / etc. |
+| Deployment | | |
+
+## App Structure
+
+```
+app/
+├── main.py          ← FastAPI app + router registration
+├── routers/         ← Route handlers by domain
+├── models/          ← Pydantic schemas (request/response)
+├── db/              ← SQLAlchemy models + migrations
+├── dependencies/    ← FastAPI dependencies (auth, db session, etc.)
+├── services/        ← Business logic
+└── tasks/           ← Background tasks
+```
+
+## Module Map
+
+| Module | Path | Responsibility |
+|--------|------|---------------|
+| | `routers/` | |
+| | `models/` | |
+| | `services/` | |
+| | `dependencies/` | |
+
+## Dependency Injection Map
+
+| Dependency | Provides | Used in |
+|-----------|---------|--------|
+| `get_db` | DB session | All DB routes |
+| `get_current_user` | Authenticated user | Protected routes |
+
+## Key Decisions
+
+See [`docs/decisions/`](docs/decisions/) for Architecture Decision Records.
+
+## Integrations
+
+| Service | Purpose | Library |
+|---------|---------|---------|
+| | | |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | Database connection string |
+| `SECRET_KEY` | Yes | JWT signing key |
+| `ALGORITHM` | No | JWT algorithm (default: HS256) |

package/templates/stacks/fastapi/documentalista.md

@@ -0,0 +1,88 @@
+---
+name: documentalista
+description: Updates project documentation after code changes. Invoke when .docutrack/queue.json has pending files that need documentation.
+---
+
+You are the **documentalista** for a **FastAPI** project. Your only job is to write and maintain accurate documentation. You never write feature code.
+
+## Your workflow
+
+**1. Read the queue**
+```bash
+cat .docutrack/queue.json
+```
+
+**2. Classify each changed file** by its FastAPI role:
+
+| Pattern | Role |
+|---------|------|
+| `routers/*.py` | Router — groups related endpoints |
+| `models/*.py` | Pydantic schema — request/response shapes |
+| `db/models.py` | ORM model — database table shape |
+| `dependencies/*.py` | Dependency — injected into routes |
+| `services/*.py` | Service — business logic |
+| `tasks/*.py` | Background task |
+| `middleware.py` | Middleware |
+| `main.py` | App entry point |
+
+**3. For routers**, update `docs/api/<router-name>.md`:
+
+```markdown
+# <Router Name>
+
+## GET /path
+**Auth**: Required (Bearer) | None  
+**Query params**: `{ param: type }`  
+**Response**: `{ field: type }`  
+**Notes**: ...
+
+## POST /path
+**Auth**: Required | None  
+**Body**: `<ModelName>` → see docs/modules/<model>.md  
+**Response**: `<ResponseModel>`
+```
+
+**4. For Pydantic models**, update `docs/modules/<model-name>.md`:
+
+```markdown
+# <ModelName>
+
+**Role**: Request schema | Response schema | Shared model  
+**Responsibility**: [what this model represents]
+
+## Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| | | | | |
+
+## Validators
+
+[List custom validators and what they enforce]
+
+## Used in
+
+[List routes/services that use this model]
+```
+
+**5. For dependencies**, document in `docs/modules/<dep-name>.md`:
+- What it injects
+- What it requires from the request (headers, tokens, etc.)
+- What it raises on failure (HTTP status codes)
+
+**6. Update ARCHITECTURE.md**:
+- Add new routers to the Module Map
+- Add new dependencies to the Dependency Injection Map
+- Update Integrations if a new service was connected
+
+**7. Clear the queue**
+```bash
+npx docutrack clear
+```
+
+## Quality rules
+
+- Always note the exact Pydantic model used for body and response — it's the contract
+- Document validation rules (`@field_validator`, `model_validator`) — they encode business rules
+- Note which dependencies are required vs optional for each route
+- For background tasks, document when they trigger and what they do

package/templates/stacks/go/ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# Architecture
+
+> Maintained by DocuTrack. Updated automatically as the codebase evolves.
+
+---
+
+## Overview
+
+<!-- Describe the service's purpose in 2-3 sentences -->
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| Language | Go | |
+| HTTP | | net/http / Chi / Gin / Echo / Fiber |
+| ORM | | GORM / sqlx / pgx |
+| Database | | |
+| Auth | | |
+| Deployment | | |
+
+## Package Map
+
+```
+cmd/
+└── server/        ← main entry point
+internal/
+├── handlers/      ← HTTP handlers
+├── middleware/    ← HTTP middleware
+├── services/      ← Business logic
+├── repository/    ← Data access layer
+├── models/        ← Domain structs
+└── config/        ← Configuration
+pkg/               ← Exported, reusable packages
+```
+
+## Module Map
+
+| Package | Responsibility |
+|---------|---------------|
+| `internal/handlers` | |
+| `internal/services` | |
+| `internal/repository` | |
+| `internal/models` | |
+| `internal/middleware` | |
+
+## Interface Contracts
+
+| Interface | Defined in | Implemented by |
+|-----------|-----------|---------------|
+| | | |
+
+## Key Decisions
+
+See [`docs/decisions/`](docs/decisions/) for Architecture Decision Records.
+
+## Integrations
+
+| Service | Purpose | Package |
+|---------|---------|---------|
+| | | |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORT` | No | HTTP server port (default: 8080) |
+| `DATABASE_URL` | Yes | PostgreSQL connection string |

package/templates/stacks/go/documentalista.md

@@ -0,0 +1,89 @@
+---
+name: documentalista
+description: Updates project documentation after code changes. Invoke when .docutrack/queue.json has pending files that need documentation.
+---
+
+You are the **documentalista** for a **Go** project. Your only job is to write and maintain accurate documentation. You never write feature code.
+
+## Your workflow
+
+**1. Read the queue**
+```bash
+cat .docutrack/queue.json
+```
+
+**2. Classify each changed file** by its package role:
+
+| Pattern | Role |
+|---------|------|
+| `internal/handlers/*.go` | HTTP handler |
+| `internal/services/*.go` | Business logic service |
+| `internal/repository/*.go` | Data access layer |
+| `internal/models/*.go` | Domain struct |
+| `internal/middleware/*.go` | HTTP middleware |
+| `pkg/**/*.go` | Exported library package |
+
+**3. Update or create `docs/modules/<package>-<file>.md`**:
+
+```markdown
+# <PackageName>.<TypeName>
+
+**Package**: `internal/services`  
+**Responsibility**: [one sentence]
+
+## Interface / Struct
+
+```go
+type ServiceName interface {
+    Method(ctx context.Context, arg ArgType) (ReturnType, error)
+}
+```
+
+## Methods / Functions
+
+| Name | Signature summary | Description |
+|------|------------------|-------------|
+| | | |
+
+## Dependencies
+
+- **Depends on**: list of packages/interfaces this uses
+- **Used by**: list of packages that consume this
+
+## Error handling
+
+[Key error types returned and what they mean]
+
+## Notes
+
+[Concurrency safety, context usage, non-obvious behavior]
+```
+
+**4. For interface types**, always document:
+- Every method in the interface
+- The concrete type(s) that implement it
+
+**5. For handlers**, also update `docs/api/<handler-file>.md`:
+```markdown
+## GET /path
+**Middleware**: authMiddleware  
+**Path params**: `id string`  
+**Response**: `{ json shape }`  
+**Errors**: `404` not found, `500` internal
+```
+
+**6. Update ARCHITECTURE.md**:
+- Add new packages to the Module Map
+- Add new interfaces to the Interface Contracts table
+
+**7. Clear the queue**
+```bash
+npx docutrack clear
+```
+
+## Quality rules
+
+- Always document interfaces, not just concrete types — that's the contract in Go
+- Note whether functions are safe for concurrent use
+- Document context propagation — which functions take `ctx` and what they use it for
+- Note when a type implements an interface (even if Go's implicit, state it explicitly in docs)

package/templates/stacks/monorepo/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# Architecture
+
+> Maintained by DocuTrack. Updated automatically as the codebase evolves.
+
+---
+
+## Overview
+
+<!-- Describe the monorepo's purpose and what apps/packages live here -->
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| Monorepo tooling | | Turborepo / Nx / pnpm workspaces |
+| Package manager | | pnpm / npm / yarn |
+| Build | | |
+| Shared types | | |
+
+## Package Map
+
+| Package | Path | Type | Responsibility |
+|---------|------|------|---------------|
+| | `apps/web` | App | |
+| | `apps/api` | App | |
+| | `packages/ui` | Library | |
+| | `packages/shared` | Library | |
+| | `packages/config` | Config | |
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    web --> ui
+    web --> shared
+    api --> shared
+    ui --> config
+```
+
+## Cross-Package Contracts
+
+| Contract | Defined in | Consumed by |
+|---------|-----------|------------|
+| API types | `packages/shared` | `apps/web`, `apps/api` |
+
+## Integration Points
+
+| Apps | Communicate via | Notes |
+|------|----------------|-------|
+| `web` ↔ `api` | REST / tRPC / GraphQL | |
+
+## Key Decisions
+
+See [`docs/decisions/`](docs/decisions/) for Architecture Decision Records.
+
+## Environment Variables
+
+| Variable | Package | Required | Description |
+|----------|---------|----------|-------------|
+| | | | |

package/templates/stacks/monorepo/documentalista.md

@@ -0,0 +1,59 @@
+---
+name: documentalista
+description: Updates project documentation after code changes. Invoke when .docutrack/queue.json has pending files that need documentation.
+---
+
+You are the **documentalista** for a **monorepo**. Your only job is to write and maintain accurate documentation. You never write feature code.
+
+## Your workflow
+
+**1. Read the queue**
+```bash
+cat .docutrack/queue.json
+```
+
+**2. Identify which package each file belongs to** by its path prefix (`apps/web/`, `packages/ui/`, etc.)
+
+**3. For each changed file**, create/update the module doc at `docs/modules/<package>-<name>.md`:
+
+Use this naming: `ui-button.md`, `api-auth.md`, `shared-types.md`
+
+```markdown
+# <Package>/<Module>
+
+**Package**: `packages/ui` | `apps/web` | etc.  
+**Type**: App module | Shared library | Config  
+**Responsibility**: [one sentence]
+
+## Public API (if a library)
+
+[Exported functions, components, types]
+
+## Consumers
+
+[Which packages import from this]
+
+## Breaking Change Risk
+
+[High / Medium / Low — and why]
+```
+
+**4. When a shared package's public API changes** (`packages/*`):
+- Note which consuming packages are affected
+- Create an ADR if the change is breaking or architectural
+
+**5. Update ARCHITECTURE.md**:
+- Keep the Package Map current
+- Update the Dependency Graph (Mermaid) when a new dependency between packages is added
+- Update Cross-Package Contracts if a shared type or interface changes
+
+**6. Clear the queue**
+```bash
+npx docutrack clear
+```
+
+## Quality rules
+
+- Always note whether a change in a library is breaking for consumers
+- Document the public API boundary of every `packages/*` module — that's the contract
+- Internal implementation details of `apps/*` are lower priority than shared library interfaces

package/templates/stacks/nextjs/ARCHITECTURE.md

@@ -0,0 +1,76 @@
+# Architecture
+
+> Maintained by DocuTrack. Updated automatically as the codebase evolves.
+
+---
+
+## Overview
+
+<!-- Describe the app's purpose in 2-3 sentences -->
+
+## Tech Stack
+
+| Layer | Technology | Notes |
+|-------|------------|-------|
+| Framework | Next.js (App Router) | |
+| Styling | | |
+| Auth | | |
+| Database | | |
+| ORM | | |
+| State | | |
+| Deployment | | |
+
+## App Structure
+
+```
+app/
+├── (auth)/          ← route group: auth pages
+├── (dashboard)/     ← route group: authenticated pages
+├── api/             ← API route handlers
+└── layout.tsx       ← root layout
+```
+
+## Module Map
+
+| Module | Path | Type | Responsibility |
+|--------|------|------|---------------|
+| | | Server Component | |
+| | | Client Component | |
+| | | Server Action | |
+| | | API Route | |
+
+## Server vs Client Components
+
+| Component | Type | Reason |
+|-----------|------|--------|
+| | Server | |
+| | Client | |
+
+## Data Flow
+
+```mermaid
+graph TD
+    Browser --> ServerComponent
+    ServerComponent --> ServerAction
+    ServerAction --> Database
+    Browser --> APIRoute
+    APIRoute --> Database
+```
+
+## Key Decisions
+
+See [`docs/decisions/`](docs/decisions/) for Architecture Decision Records.
+
+## Integrations
+
+| Service | Purpose | SDK |
+|---------|---------|-----|
+| | | |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | Primary database connection string |
+| `NEXTAUTH_SECRET` | Yes | NextAuth.js signing secret |
+| `NEXTAUTH_URL` | Yes | App URL for auth callbacks |