Skip to main content
Version: 1.0.0-beta

Developer Setup

Set up your local development environment for AIIA.

Prerequisites​

ToolVersion
Docker & Compose24.0+ / v2
Python3.11+
Node.js20+
npm9+
Git2.40+

Setup Steps​

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​

# Terminal 1: Backend
cd backend && uvicorn app.main:app --reload --port 8005

# Terminal 2: Frontend
cd frontend && npm run dev -- -p 3006

6. Verify​

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​

ConventionRule
BackendPython 3.11+, type hints, async/await
FrontendTypeScript strict, functional components
DatabaseSQLModel with underscore table names
APIREST, JSON, consistent error format
AuthJWT via Keycloak, RBAC at API layer
AuditEvery CUD creates AuditLogEvent
i18nTranslation keys, no hardcoded strings