Developer Setup
Set up your local development environment for AIIA.
المتطلبات المسبقة
| Tool | Version |
|---|---|
| Docker & Compose | 24.0+ / v2 |
| Python | 3.11+ |
| Node.js | 20+ |
| npm | 9+ |
| Git | 2.40+ |
Setup الخطوات
1. Clone the Repository
git clone <repo-url>
cd aiia
2. Backend Setup
cd backend
python -m venv venv
source venv/bin/activate # macOS/Linux
pip install -r requirements.txt
cp .env.example .env
# Edit .env
3. Frontend Setup
cd frontend
npm install
cp .env.example .env.local
# Edit .env.local
4. Start Infrastructure
docker compose up -d postgres redis minio keycloak
5. Run Development Servers
# Terدقيقةal 1: Backend
cd backend && uvicorn app.main:app --reload --port 8005
# Terدقيقةal 2: Frontend
cd frontend && npm run dev -- -p 3006
6. Verify
- Frontend: http://localhost:3006
- Backend: http://localhost:8005/api/v1/docs
- Keycloak: http://localhost:8080
Debug Authentication
For development, enable debug auth:
ENVIRONMENT=development
DEBUG_AUTH_ENABLED=true
DEBUG_AUTH_SECRET=your-debug-secret
Then authenticate with:
curl -H "Authorization: Bearer debug-admin" http://localhost:8005/api/v1/engagements
Project Structure
aiia/
├── backend/
│ ├── app/
│ │ ├── api/routers/ # 57 API routers
│ │ ├── models/ # 45+ SQLModel entities
│ │ ├── services/ # Business logic
│ │ ├── core/ # Middleware, config
│ │ └── db/ # Database engine, RLS
│ └── requirements.txt
├── frontend/
│ ├── app/ # 67 Next.js pages
│ ├── components/ # 69 React components
│ ├── lib/ # Utilities, API client
│ └── package.json
├── docs-site/ # Docusaurus documentation
├── docker-compose.yml
└── .env.example
Code Conventions
| Convention | Rule |
|---|---|
| Backend | Python 3.11+, type hints, async/await |
| Frontend | TypeScript strict, functional components |
| Database | SQLModel with underscore table names |
| API | REST, JSON, consistent error format |
| Auth | JWT via Keycloak, RBAC at API layer |
| Audit | Every CUD creates AuditLogEvent |
| i18n | Translation keys, no hardcoded strings |