Project Structure

This page documents the directory layout and key files in the Aero2 codebase.

Directory Tree

aero2/
+-- src/
|   +-- backend/
|   |   +-- index.ts              # Main Hono app, route mounting, global middleware
|   |   +-- rp.ts                 # Relying Party routes (external IdP OAuth flow)
|   |   +-- op.ts                 # OIDC Provider routes (authorize, token, userinfo, revoke)
|   |   +-- idp.ts                # Identity Provider CRUD API
|   |   +-- clients.ts            # OAuth client CRUD API
|   |   +-- roles.ts              # Role and permission management API
|   |   +-- jwks.ts               # JWKS Durable Object (key generation, rotation, signing)
|   |   +-- users.ts              # User management API
|   |   +-- sessions.ts           # Session management API
|   |   +-- audit.ts              # Audit log API
|   |   +-- middleware/
|   |   |   +-- auth.ts           # Authentication (JWT verification) and authorization (RBAC)
|   |   |   +-- ratelimit.ts      # Rate limiting middleware
|   |   +-- utils/
|   |       +-- token.ts          # JWT signing and verification utilities
|   |       +-- crypto.ts         # PBKDF2, AES-256-GCM, HMAC utilities
|   +-- frontend/
|       +-- App.tsx               # Root React component
|       +-- routes.tsx            # React Router configuration
|       +-- pages/                # React page components
|       |   +-- Login.tsx         # Login page
|       |   +-- Dashboard.tsx     # Main dashboard
|       |   +-- Admin*.tsx        # Admin management pages
|       |   +-- OAuthCallback.tsx # OAuth callback handler
|       +-- contexts/
|       |   +-- AuthContext.tsx    # Authentication context provider
|       +-- components/
|           +-- ui/               # Reusable UI components (Button, Card, Input, etc.)
+-- migrations/
|   +-- 0001_initial_schema.sql   # Initial database schema
+-- tests/
|   +-- *.test.ts                 # Vitest unit and integration tests
+-- docs/
|   +-- pages/                    # Documentation site (Nextra/MDX)
+-- wrangler.json                 # Cloudflare Worker configuration
+-- package.json                  # Dependencies and scripts
+-- tsconfig.json                 # TypeScript configuration
+-- vitest.config.ts              # Vitest configuration
+-- biome.json                    # Biome linter configuration
+-- .dev.vars                     # Local development secrets (gitignored)
+-- .github/
    +-- workflows/                # GitHub Actions CI/CD

Key Files Explained

Backend

File	Purpose
`src/backend/index.ts`	Entry point. Creates the Hono app, mounts all middleware (security headers, CSRF, CORS, rate limiting), mounts route sub-apps (OP, RP, API), and exports the Worker default handler plus the JWKS Durable Object class.
`src/backend/op.ts`	OIDC Provider implementation. Handles `/oauth2/authorize`, `/oauth2/token`, `/oauth2/userinfo`, `/oauth2/revoke`, `/oauth2/jwks.json`, and `/.well-known/openid-configuration`.
`src/backend/rp.ts`	Relying Party implementation. Handles `/rp/authorize/:idp` (start external OAuth flow) and `/rp/callback/:idp` (handle callback, create/link user, create session).
`src/backend/idp.ts`	Identity Provider CRUD. Endpoints for listing, creating, updating, and deleting IdP configurations.
`src/backend/clients.ts`	OAuth Client CRUD. Endpoints for managing OAuth clients (create with hashed secret, list, update, delete).
`src/backend/roles.ts`	RBAC management. Endpoints for roles, permissions, role-permission mappings, and user-role assignments.
`src/backend/users.ts`	User management. List users with pagination/filtering, get user details, update user, disable/enable user.
`src/backend/sessions.ts`	Session management. List active sessions, revoke sessions, cleanup expired sessions.
`src/backend/audit.ts`	Audit log. Log security events, query audit logs with filtering and pagination.
`src/backend/jwks.ts`	JWKS Durable Object. Manages RSA key pairs for JWT signing. Handles key generation, rotation (every 24 hours), bounded storage (MAX_KEYS=3), and exposes the JWKS endpoint.
`src/backend/middleware/auth.ts`	Authentication middleware that verifies JWTs (session or bearer tokens) and authorization middleware that checks RBAC permissions.
`src/backend/utils/token.ts`	JWT utilities: sign tokens via the Durable Object, verify tokens against JWKS, build claims objects.
`src/backend/utils/crypto.ts`	Cryptographic utilities: PBKDF2 password hashing, AES-256-GCM encryption/decryption, HMAC hashing, constant-time comparison.

Frontend

File	Purpose
`src/frontend/App.tsx`	Root component. Sets up AuthContext provider and React Router.
`src/frontend/routes.tsx`	Route definitions. Maps URL paths to page components, applies auth guards.
`src/frontend/contexts/AuthContext.tsx`	Authentication context. Provides `user`, `isAuthenticated`, `isLoading`, `signOut()` to all components.
`src/frontend/pages/`	Page components for login, dashboard, admin panels, profile, etc.
`src/frontend/components/ui/`	Reusable UI components: Button, Card, Input, Modal, Spinner, Toast, etc.

Configuration

File	Purpose
`wrangler.json`	Cloudflare Worker config: bindings (D1, Durable Objects), routes, environment variables, compatibility settings.
`vitest.config.ts`	Test config using `@cloudflare/vitest-pool-workers` for Workers-compatible test execution.
`biome.json`	Linting and formatting rules for TypeScript and CSS.

Where to Add New Features

What you are adding	Where to put it
New API endpoint	Create a Hono sub-app in `src/backend/` and mount it in `index.ts`
New middleware	Add to `src/backend/middleware/` and apply in `index.ts`
New utility function	Add to `src/backend/utils/`
New database table	Create a migration file in `migrations/`
New React page	Add to `src/frontend/pages/` and register in `routes.tsx`
New UI component	Add to `src/frontend/components/ui/`
New test	Add to `tests/` following existing naming conventions
New documentation	Add MDX file to `docs/pages/`