# Project Guide: {{ project_name }}

This guide provides everything you need to develop, test, and deploy **{{ project_name }}**.

---

## 🚀 Project Overview

{{ project_name }} is a high-performance backend generated by [NIKAME](https://github.com/nikame-framework/nikame). 

### Selected Modules
{% for module in overviews %}
- **{{ module.name }}**: {{ module.text }}
{% endfor %}

### Active Features
{% for feature in active_features %}
- **{{ feature }}**
{% endfor %}

---

## 🛠 Prerequisites

To run this project, you need:
- **Docker & Docker Compose**: (v24.0+)
- **Python**: (v3.11+)
- **Curl**: For testing APIs
{% if 'ngrok' in active_modules %}
- **Ngrok Account**: For local tunneling
{% endif %}

---

## ⚙️ Environment Setup

Copy `.env.generated` to `.env` and fill in the required values.

### Important Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `APP_ENV` | Environment (local, staging, prod) | Yes | `local` |
{% for mod in active_modules %}
{% if mod == 'postgres' %}
| `POSTGRES_PASSWORD` | Password for the primary database | Yes | - |
{% elif mod == 'redis' or mod == 'dragonfly' %}
| `REDIS_URL` | Connection string for cache | Yes | `redis://cache:6379` |
{% elif mod == 'ngrok' %}
| `NGROK_AUTHTOKEN` | Your ngrok authentication token | Yes (for tunneling) | - |
{% endif %}
{% endfor %}

---

## 🏃 Starting the Project

1. **Start all services**:
   ```bash
   nikame up
   ```
2. **Verify health**:
   ```bash
   nikame ps
   ```
   All containers should show `Up (healthy)`.

---

## 🔗 Service URLs

| Service | Local URL | Usage | Default Credentials |
|---------|-----------|-------|---------------------|
{% for item in urls %}
| {{ item.label }} | `{{ item.url }}` | {{ item.usage }} | `{{ item.creds }}` |
{% endfor %}

---

## 📖 API Usage

### Endpoints
{% for example in api_examples %}
#### {{ example.name }}
- **Description**: {{ example.desc }}
- **Command**:
  ```bash
  {{ example.curl }}
  ```
{% endfor %}

---

## ✨ Feature Guides

{% for feature in feature_guides %}
### {{ feature.title }}
{{ feature.content }}

{% endfor %}

---

## 🔄 Integrations

How the services connect:
{% for integration in integrations %}
- **{{ integration.target }}**: {{ integration.description }}
{% endfor %}

---

## 👷 Development Workflow

### Adding a New Endpoint
1. Open `app/main.py`.
2. Add a new route handler using `@app.get` or `@app.post`.

### Database Migrations (Alembic)
If you change your SQLAlchemy models:
```bash
nikame exec api alembic revision --autogenerate -m "description"
nikame exec api alembic upgrade head
```

### Background Jobs (Celery)
If background jobs are enabled, add new tasks in `app/worker.py` and call them with `.delay()`.

---

## 📊 Monitoring

- **Grafana**: Open `http://localhost:3000`. 
- **Dashboards**: Pre-built dashboards for FastAPI, Postgres, and JVM (if applicable).
- **Alerts**: Alerts are configured in Prometheus and sent to Alertmanager.

---

## 🕵️ Troubleshooting

| Issue | Potential Cause | Fix |
|-------|-----------------|-----|
{% for item in troubleshooting %}
| {{ item.issue }} | Service down or config error | `{{ item.fix }}` |
{% endfor %}
| Container fails to start | Port conflict | Check `docker ps` for used ports or use `nikame stop` |

---

## 📇 Quick Reference Card

| Action | Command |
{% for cmd in commands %}
| {{ cmd.desc }} | `{{ cmd.cmd }}` |
{% endfor %}
| Deploy to {{ environment }} | `nikame deploy` |

---
*Generated by NIKAME on {{ now }}*
