fastapi-microservice/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
fastapi-microservice	Bootstrap FastAPI: SQLAlchemy, auth, Docker, one-pass build.	1.0.0	Hermes Agent	MIT	linux macos	hermes tags related_skills fastapi microservice bootstrap backend python docker task-list-execution writing-plans

FastAPI Microservice Bootstrap

When to Use

The user asks to create a new FastAPI-based microservice. Signals:

• "создай каталог /opt/xxx, спланируем и напишем сервис"
• "нужен сервис для X с API на FastAPI"
• "bootstrap a new API service for Y"
• Any request where the output is a Python/FastAPI server with routes, database, and external integration

Core Rules

1. No analysis preamble — start immediately

The user says "создай каталог и спланируем" — your first action is to create the directory. Do not:

• ❌ Summarize the requirement back to them
• ❌ Ask clarifying questions about scope
• ❌ Propose technology choices for approval
• ❌ Write a multi-step plan document before coding

✅ Instead: mkdir -p /opt/project/app → start writing files

Investigation is part of execution, not preparation. If you need to check Python version, installed packages, or port availability, do it as the first action of writing code, not as a preamble.

2. Build in layers, bottom-up

Write files in this order for maximum efficiency:

Layer 1 — Foundation
  ├── requirements.txt
  ├── .env.example
  ├── __init__.py files (empty, create dirs)
  ├── app/config.py           # pydantic-settings from env
  ├── app/security.py         # encryption, key generation
  ├── app/database.py         # async engine + session
  └── app/models.py           # ORM models (User, Account, etc.)

Layer 2 — Business logic
  ├── app/converters/         # domain-specific converters
  └── app/vk_client.py        # external API clients

Layer 3 — API
  ├── app/api/schemas.py      # Pydantic request/response
  ├── app/api/deps.py         # auth dependencies
  └── app/api/v1.py           # route handlers

Layer 4 — Entry point
  └── app/main.py             # FastAPI app + lifespan

Layer 5 — Infrastructure
  ├── Dockerfile
  ├── docker-compose.yml
  ├── Makefile
  └── .gitignore

3. Generate secrets and verify immediately

After writing code, do NOT stop at "code is written". Do:

1. Generate encryption key: python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" > secrets/token_encryption_key
2. Install deps: pip install -r requirements.txt
3. Verify all modules import: python3 -c "from app import ..."
4. Start server and test: curl health endpoint
5. Test at least one API endpoint (e.g. convert endpoint if it's a converter service)

4. Write all project files in one pass

Do not save README.md and STATUS.md separately from code. Write them last, after the code compiles and runs:

• README.md — API reference, usage examples, security, run instructions
• STATUS.md — implementation status table, phases, architecture diagram, how to run
• Dockerfile — multi-stage, slim, read-only rootfs, non-root user
• docker-compose.yml — service + volume + secret + healthcheck
• Makefile — dev/install/run/test/key/user commands

5. Security by default

Every microservice needs:

• Encrypted secrets — Fernet (AES-128-CBC + HMAC-SHA256), key from file/secret, NOT in code
• API key auth — sha256 hashed, not stored in plaintext
• API key ≠ external token — the API key lets you use the service, not read the upstream token
• Minimal scope — upstream tokens should have minimal permissions (e.g. VK wall scope only)
• Docker read-only rootfs — only /data writable
• Non-root user in Docker container

Log these in README.md as a security matrix table.

Expected File Structure

/opt/<project-name>/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── models.py
│   ├── security.py
│   ├── vk_client.py          # or external_api.py
│   ├── converters/
│   │   ├── __init__.py
│   │   └── markdown_to_vk.py # or relevant converter
│   └── api/
│       ├── __init__.py
│       ├── schemas.py
│       ├── deps.py
│       └── v1.py
├── tests/
│   └── (TODO after code)
├── secrets/
│   └── token_encryption_key  # NOT in git (.gitignore it)
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
├── .gitignore
├── Makefile
├── README.md
└── STATUS.md

Common Pitfalls

Pitfall	Fix
Writing README before code runs	Write docs last — they reflect what's real
Asking for approval on every file	Write all files in one batch, then verify
Skipping security docs	Include security matrix table in README
Not testing the API after writing code	Always start server and curl at least health + one endpoint
Using & in foreground terminal command	Use terminal(background=True) for server, then curl
Hand-typing code that could be written	Batch independent file writes in the same turn
Explaining the design before building	Say "Начинаю" and write files — the code IS the design

Verification Checklist

After writing all code:

• pip install -r requirements.txt succeeds
• All modules import: python3 -c "from app import config, database, models, security, ..."
• Encryption key generated and stored in secrets/
• Encrypt/decrypt round-trip works
• API keys generate and verify
• Converter (if any) produces correct output
• Server starts: uvicorn app.main:app --host 0.0.0.0 --port N
• GET /api/v1/health returns {"status":"ok"}
• At least one POST endpoint responds correctly (e.g. convert or account create)
• Swagger UI at /docs returns 200
• Dockerfile builds (if docker is available)

Related Skills

• task-list-execution — for executing tasks from STATUS.md files
• writing-plans — for multi-step implementation plans with subagent delegation