mockapi/PROJECT_PLAN.md

Configurable Mock API with Admin Interface - Project Plan

Architecture Decisions (from @architect)

Technology Stack

• Framework: FastAPI (over Flask) for automatic API documentation, async support, type safety.
• Server: Waitress as production WSGI server.
• Database: SQLite with SQLAlchemy ORM, aiosqlite for async.
• Template Engine: Jinja2 with sandboxed environment.
• Admin UI: Custom Jinja2 templates with Bootstrap 5 CDN, session-based authentication.

Database Schema

• endpoints table: id, route (VARCHAR), method (VARCHAR), response_body (TEXT), response_code (INTEGER), content_type (VARCHAR), is_active (BOOLEAN), variables (JSON), headers (JSON), delay_ms (INTEGER), created_at, updated_at.
• Unique constraint on (route, method).

Application Architecture

• Repository-Service-Controller pattern with Observer pattern for dynamic route updates.
• Modules: database, models, repositories, services, controllers, observers, schemas, middleware, utils.

Dynamic Route Registration

• RouteManager service registers/unregisters endpoints at runtime via FastAPI's add_api_route.
• Observer pattern triggers route refresh on CRUD operations.

Template Variable Rendering

• Variable sources: path params, query params, request headers, request body, system variables, endpoint defaults.
• Jinja2 with StrictUndefined to prevent silent failures.

Admin Interface

• Simple credential store (admin username/password hash from env vars).
• Session-based authentication with middleware protecting /admin/* routes.
• Pages: Login, Dashboard, Endpoint List, Endpoint Editor, Request Logs (optional).

Project Structure

mock_api_app/              # Align with user request
├── app.py
├── config.py
├── database.py
├── dependencies.py
├── middleware/
├── models/
├── repositories/
├── services/
├── controllers/
├── observers/
├── schemas/
├── static/
├── templates/
├── utils/
├── requirements.txt
├── README.md
└── .env.example

Roadmap

Phase 1: Foundation

• Create project directory and structure
• Set up SQLAlchemy model Endpoint
• Configure FastAPI app with Jinja2 templates
• Write requirements.txt

Phase 2: Core Services

• Implement EndpointRepository
• Implement RouteManager service
• Implement TemplateService with variable resolution

Phase 3: Admin Interface

• Authentication middleware
• Admin controller routes
• HTML templates (Bootstrap 5 CDN)

Phase 4: Integration

• Connect route observer
• Add request logging (optional)
• Health check endpoints

Phase 5: Production Ready

• Waitress configuration
• Environment variable configuration
• Comprehensive README

Phase 6: OAuth2 Provider Implementation

6.1 Database & Models

• Extend Endpoint model with requires_oauth and oauth_scopes columns
• Create OAuth models: OAuthClient, OAuthToken, OAuthUser
• Implement database migrations with foreign key support

6.2 Repositories & Schemas

• Create OAuth repository classes (OAuthClientRepository, OAuthTokenRepository, OAuthUserRepository)
• Create Pydantic schemas for OAuth entities with validation

6.3 Services

• TokenService: JWT generation/validation with database revocation checking
• OAuthService: Grant flow strategies (authorization_code, client_credentials, refresh_token)
• ClientService: Client validation with bcrypt secret verification
• ScopeService: Scope validation and checking
• Update RouteManager to check OAuth2 token validation

6.4 Controllers (Current Phase)

• OAuth2 endpoint controllers (/oauth/authorize, /oauth/token, /oauth/userinfo)
• Admin OAuth2 management controllers (clients, tokens, users)
• HTML templates for OAuth2 admin pages

6.5 Configuration & Integration

• Update config.py with OAuth2 settings
• Update app.py to include OAuth2 routers
• Integrate OAuth2 protection into existing admin authentication

6.6 Testing

• Unit tests for OAuth2 services and repositories
• Integration tests for OAuth2 flows
• End-to-end tests with protected endpoints

Dependencies

See requirements.txt in architect spec.

Security Considerations

• Template sandboxing
• SQL injection prevention via ORM
• Admin authentication with bcrypt
• Route validation to prevent path traversal
• OAuth2 security: client secret hashing, token revocation, scope validation, PKCE support (future)

Status Log

• 2025-03-13: Architectural specification completed by @architect.
• 2025-03-13: Project plan created.
• 2026-03-14: Project cleanup and optimization completed. All phases implemented. Integration tests passing. Project ready for demonstration/testing.
• 2026-03-14 (evening): OAuth2 provider implementation started. Phases 6.1-6.3 completed (Database, Models, Repositories, Schemas, Services). Phase 6.4 (Controllers) in progress.
• 2026-03-14 (later): OAuth2 controllers completed (authorize, token, userinfo, introspection, revocation, OpenID discovery). Admin OAuth2 management routes and templates implemented. Configuration updated. Integration with main app completed.
• 2026-03-14 (final): Integration tests for OAuth2 flows completed and passing. OAuth2 provider fully functional.

Current Status (2026-03-14)

• ✅ Phase 1: Foundation completed
• ✅ Phase 2: Core Services completed
• ✅ Security fixes applied (critical issues resolved)
• ✅ Phase 3: Admin Interface completed
• ✅ Phase 4: Integration completed
• ✅ Phase 5: Production Ready completed
• ✅ Phase 6.1: OAuth2 Database & Models completed
• ✅ Phase 6.2: OAuth2 Repositories & Schemas completed
• ✅ Phase 6.3: OAuth2 Services completed
• ✅ Phase 6.4: OAuth2 Controllers completed
• ✅ Phase 6.5: Configuration & Integration completed
• ✅ Phase 6.6: Testing completed

Next Steps

1. Update documentation with OAuth2 usage examples.
2. Deploy to production environment (if needed).
3. Consider adding PKCE support for public clients.
4. Add more advanced OAuth2 features (e.g., token introspection, JWKS endpoint).